GH-700 study guide: Copilot custom agents and guardrails

GH-700 · Enhance productivity by using GitHub Copilot (20–25% of the exam)

"Enhance productivity by using GitHub Copilot" is one of the four skill areas of exam GH-700, worth 20–25% of the exam. One of its task groups is "Create and manage custom agents". It tests whether you can define a specialist agent for repeatable work, save it where the right people can use it, limit what it can do, and check what it did. The official study guide's description of who the exam is for also expects you to tell Copilot cloud agent apart from custom agents, so this lesson starts there.

Now you can get Claude Certified and earn OpenAI badges and certifications too Here's how

What the official study guide covers

What the guide lists	What it means in practice
Create a custom agent by adding web search to instructions or prompts	Write an agent profile, give it a web tool where the surface has one, and say in its prompt when to use it
Save an agent to a GitHub project	Commit the profile to the right folder so the agent appears in the agent picker
Implement agent guardrails	Limit tools, name MCP tools exactly, and control when the agent can be chosen
Review custom agent activities	Read the pull request note, session logs and audit log events
Audience profile: differentiating between GitHub Copilot cloud agents and custom agents	Cloud agent does the work; a custom agent is a role it can take on

Cloud agent, custom agents, instructions and skills

Copilot cloud agent works in the background on GitHub.com. It edits files and runs tests in a temporary cloud environment, then pushes to a branch and can open a pull request.

A custom agent is not a separate product. It is a Markdown file, called an agent profile, that defines a specialist role: a description, a prompt and, optionally, a list of allowed tools. GitHub's docs call custom agents "specialized versions of the Copilot agent". On GitHub.com you pick one from a dropdown "instead of the default cloud agent", and the work still runs as a cloud agent session. The same profile also works in Copilot CLI, the Copilot app and code editors such as VS Code (IDEs).

Feature	What it is	When it applies
Copilot cloud agent	The agent that does delegated work on GitHub.com	When you start a task or assign it an issue
Custom agent	A reusable role with its own prompt and tool list	When selected, or picked by Copilot for a matching task
Custom instructions	Standing rules, such as `.github/copilot-instructions.md`	In every interaction within their scope
Agent skill	A `SKILL.md` folder of steps for one kind of task	When Copilot judges the task needs it

GitHub's comparison page puts it simply: instructions for conventions, a skill for a repeatable procedure, and a custom agent for "a reusable specialist with a particular approach and toolset".

Create a custom agent

An agent profile is a file ending in .agent.md. The top holds YAML frontmatter, a block of settings between two --- lines. Everything below it is the agent's prompt, up to 30,000 characters.

---
name: requirements-reviewer
description: Reviews requirement documents for missing acceptance criteria
tools: ["read", "search", "edit"]
---
Review the files in docs/requirements. Check that each requirement has
measurable acceptance criteria. Write your findings to
docs/reviews/requirements-review.md. Do not change any other file.

Property	What it does
`description`	Required. Says what the agent does, which helps Copilot match it to tasks
`tools`	Optional allow-list, meaning the only tools the agent may use. Omitted means all tools
`target`	`vscode` or `github-copilot` limits where the agent appears
`disable-model-invocation`	`true` stops cloud agent choosing the agent automatically
`user-invocable`	`false` stops people selecting it; it can only be called by another agent or workflow, not picked from the menu
`mcp-servers`	MCP servers (connectors to other systems' tools) for this agent only; not used in IDEs

On GitHub.com, open the agents tab at github.com/copilot/agents, choose the repository, and choose "Create an agent". GitHub opens a template, my-agent.agent.md, in .github/agents. Rename it, edit it, then commit and merge it into the default branch.

Adding web search to instructions or prompts

Web access needs two parts. The tool must be available to the agent, and the prompt must say when to use it, for example "Fetch the supplier's published price list and cite its URL". A prompt that asks for web search is not enough on its own: the agent also needs a web tool, and whether one exists depends on the surface (the place you use Copilot: GitHub.com, Copilot CLI, VS Code or the Copilot app):

Surface	What the docs say
Copilot cloud agent	The `web` tool alias (web search and web fetch) is "currently not applicable for cloud agent". A firewall that administrators configure also limits internet access
Copilot CLI	A built-in `web_fetch` tool fetches web pages; permission rules can restrict which sites it may open. The `/research` command runs research using GitHub search and web sources
VS Code	You type `#web/fetch` in your prompt to use the web fetch tool. If you address `@github`, `#web` asks for a web search
Copilot Chat on GitHub.com	Can use web search results when an administrator has enabled it

Unrecognised tool names are ignored, not treated as errors, so one profile can list tools that only some products support. web is a recognised alias that the docs mark "currently not applicable for cloud agent", so listing it gives cloud agent no web access, while clients that support it can use it. For a cloud agent task that needs outside information, put it in the repository or the issue, or connect a suitable MCP server.

Save an agent to a GitHub project

Saving an agent means committing its profile to a folder Copilot reads. The folder sets who can use it.

Where you save it	Who can use it
`.github/agents/` in a repository	People working in that repository
`agents/` in the organization's `.github` or `.github-private` repository (a repository with that exact name holds settings for the whole organization)	The whole organization
`agents/` in the enterprise's designated `.github-private` repository	The whole enterprise
`~/.copilot/agents/` in your home folder (Copilot CLI) or your VS Code user profile	Only you

On GitHub.com the agent appears once the file is merged into the default branch. If two levels have an agent with the same file name, the lowest level wins: repository beats organization, which beats enterprise.

The current docs do not describe saving a custom agent to GitHub Projects, the planning boards. A changelog post does describe showing agent sessions in issues and project views. The closest documented meaning is in Copilot CLI: /agent offers to save a new agent as Project (.github/agents/ in the repository, shared with the team) or User (~/.copilot/agents/, just you).

For organization agents, GitHub documents a test-then-release path. Test the profile in .github/agents inside the .github-private repository, where only people with access to that repository can use it. Then move it to the root agents folder to release it.

Implement agent guardrails

A guardrail is a limit set in configuration, not a request in the prompt. The prompt guides the model; the tool list decides what it can do.

Guardrail	How it works
Tool allow-list	`tools: ["read", "search"]` gives a read-only reviewer; `tools: []` allows no tools
MCP tool naming	Allow one MCP tool with `server-name/tool-name`, or all of a server's tools with `server-name/*`
Built-in MCP servers	`github` is read-only and scoped to the current repository; `playwright` (a browser tool) can open only pages on the agent's own machine, not the internet
Invocation settings	`disable-model-invocation: true` means a person must select the agent
Review of profile changes	GitHub recommends a CODEOWNERS file, which names who must approve changes, plus the "Require review from Code Owners" rule

For example, an operations team connects a ticketing MCP server called tickets with get_ticket, update_ticket and close_ticket. A summariser agent with tools: ["read", "search", "edit", "tickets/get_ticket"] can read tickets but cannot change or close them.

Cloud agent's own protections still apply on GitHub.com. It can push to only a single branch (a new copilot/ branch, or the branch of the pull request where it was mentioned), cannot approve or merge its pull request, and by default GitHub Actions workflows wait for approval from someone with write access.

Review custom agent activities

The pull request. When Copilot opens a pull request, the description notes which custom agent did the work.
The session log. Open the session from the agents tab to see Copilot's reasoning, the tools it called, token use and session length.
The commits. Copilot authors them, with the person who started the task as co-author, and each commit message links to the session log.
The audit log. Owners filter by actor:Copilot to see agent activity. Events include the action, actor_is_agent: true, an agent_session_id and the user who started the work. Events are kept for 180 days.

Do not confuse actor:Copilot with action:copilot, which shows Copilot plan changes such as settings, policies and licences.

Rules that decide exam answers

A custom agent is a role; cloud agent is the worker. Selecting a custom agent on GitHub.com still runs a cloud agent session.
Only description is required. Omitting tools allows everything.
For web access, check the surface. The web alias does nothing on cloud agent today.
The folder sets the reach: .github/agents for one repository, agents in the org's .github or .github-private repository for the organization.
To stop automatic use, set disable-model-invocation: true. To stop people selecting an agent, set user-invocable: false.
For organization-wide agent activity, filter the audit log by actor:Copilot; for one task, read its session log.

Two sample questions

These are original Timo practice questions, not official exam questions.

Question 1

A finance operations team has a custom agent that updates records through an MCP server. They want it to run only when a team member deliberately chooses it, never because Copilot matched it to a task. Which frontmatter setting meets this need?

A. user-invocable: falseB. disable-model-invocation: trueC. target: github-copilotD. tools: ["read", "records/update_record"]

Answer: B. disable-model-invocation: true stops cloud agent choosing the agent from task context, so a person must select it. A does the opposite: people can no longer select it at all. C limits which environment shows the agent, not who starts it. D narrows the agent's tools but does not stop Copilot choosing it automatically.

Question 2

A compliance lead wants one list of the actions Copilot agents, including custom agents, took across the organization's repositories this month. Where should they look?

A. The organization audit log, filtered by actor:CopilotB. The organization audit log, filtered by action:copilotC. The session log of each pull request Copilot openedD. The "All sessions" view on each repository's Agents tab

Answer: A. actor:Copilot returns agent activity, with the session ID and the person who started each task. B returns Copilot plan changes, such as policy and licence events, not agent actions. C and D show one session or one repository at a time, not a single organization-wide list.

Build exercise

Use a test repository where you can run Copilot cloud agent.

Add docs/requirements/login.md with three short requirements, one without acceptance criteria.
Open github.com/copilot/agents, select the repository, choose "Create an agent", and name the file requirements-reviewer.agent.md.
Paste the profile from "Create a custom agent", add disable-model-invocation: true under the tools line, then commit and merge to the default branch.
Refresh the agents tab, select requirements-reviewer, and ask: "Review the requirements, write your findings and create a pull request."
When the pull request opens, its description should name the custom agent. In the session log, the tool calls should be reads, searches and edits only.
Optional: add "web" to the tools list and ask the agent to check a public web page. The session log should show no web tool in use.

Practise this topic

Start with the free GH-700 practice test of 20 questions. The GH-700 practice tests give you 200 questions in four timed 50-question mocks for US$15, and the GH-700 prep material has one module per skill area with guided labs for US$15, or US$25 for both, at GH-700 practice tests and prep material. See the GH-700 exam guide for the exam format.

Now you can get Claude Certified and earn OpenAI badges and certifications too

Register for all four Claude certification exams through Amotion AI, which is Certified in the Claude Partner Network. Claude Certified Associate covers business and knowledge work, not coding.
Take 11 OpenAI PartnerU learning programs with assessments and course-completion certificates, and work towards the expert badges for ChatGPT, Codex and APIs.
Practise with 20 full-length Claude mock exams.

Join Timo for Claude and OpenAI certifications

Sources

Independent Timo practice material. Not affiliated with or endorsed by GitHub or Microsoft.