Domain 5 of 6 · Chapter 4 of 4

Manage agent lifecycles within workflows

Unlock the complete study guide.

Bundled into the existing Developing in Agentic AI Systems premium course — no separate purchase.

14-day money-back guarantee — no questions asked.

Included in this chapter:

  • Where a worker lives decides who can use it
  • A profile's two halves: frontmatter configures, body instructs
  • The required field is the one that describes the work
  • Two independent switches: who may pick it, and whether it is picked for you
  • Registering specialists in a Copilot SDK session
  • Starting an existing specialist from the CLI
  • Versioning: a commit SHA, a branch, and a pull request that remembers
  • When a replacement takes no effect: the most local copy of an identity wins
  • When a replacement takes no effect: repository MCP settings are applied last
  • Capability parity: tools that widen, tools that vanish, and tools that outrank
  • Model fallback: list models in priority order
  • SDK skills: a replacement worker must opt in to its own
  • Retiring an agent: remove it through the source that supplies it
  • Retiring a session without destroying its work
  • A record you cannot see is usually a record behind a filter

Adding, versioning, and retiring a worker, by the source that supplies it

SourceHow the worker is addedWhich version a run getsHow it is retired
Workspace (repository level)A .agent.md profile committed under .github/agents, with identity and capabilities in the YAML frontmatter and role instructions in the Markdown body; the deprecated chat.agentFilesLocations setting adds other workspace folders for the Local agent onlyFor a task assigned on GitHub, including one started with gh agent-task create --custom-agent, the latest profile on the repository and branch the task selects, identified by that file's Git commit SHADelete the profile file, or use the delete action in the Configure Custom Agents menu
User-level agents folderA profile in the user-level agents folder; Copilot sessions on Agent Host read ~/.copilot/agents rather than VS Code profile user dataWhatever the file currently holds for that user, across all of their workspacesDelete the profile file from the user-level folder
Organization or enterpriseA central definition; an organization-level one is surfaced in VS Code once organization-agent discovery is enabled for the signed-in accountThe central definition, unless a more local level - a repository copy with the same file-name identity - overrides itWithdraw the central definition; a repository copy of the same identity keeps winning until it is removed
ExtensionAn agent contributed by an installed VS Code extensionWhatever the installed extension version providesUninstall the extension; hiding the agent in the agent picker only changes visibility
Copilot SDK sessionA customAgents definition passed when the session is created, each needing a unique name and a promptWhatever the application passes at session creation, including its own skills, tools and modelStop passing the definition; the registration lives and dies with the session

Decision tree

What are you doing to the worker? Adding one.Who must be able to use it? add One workspace: commit a .agent.mdprofile under .github/agents One person, every workspace: theAgent Host user folder ~/.copilot/agents A whole organization: define itcentrally, then enable organizationagent discovery Everyone with the extension: anagent contributed by an installedVS Code extension One session: an SDK customAgentsdefinition passed when theapplication creates the session Updating or replacing one.Which case are you in? change Only new work must change: publish tothe branch the tasks select; a new tasktakes the latest profile Work in an open pull request: it keepsthe version that opened it, so assignthat work as a new task It loaded and changed nothing: find thewinning level, the repository MCPsettings, or the calling prompt file Retiring one.The agent, a session, or a missing record? retire The agent: remove it through the sourcethat supplies it. Hiding it in the agentpicker is not removing it A local worktree session: archive it(commits, keeps the branch). To delete,commit first: deletion is final A cloud-agent session: archive it.Cloud sessions can be archivedbut not deleted You cannot find it: check the filter,Archived in the Chat view or Donein the Agents window
Cheat sheet

Cheat sheet

  • A workspace agent profile adds a reusable specialist to the repository
  • A GitHub custom-agent profile requires a purpose and capability description
  • Agent Host loads reusable user agents from the Copilot agents directory
  • The extra agent-file locations setting reaches only the Local agent
  • Organization-agent discovery must be enabled in VS Code
  • Start an existing custom agent from the CLI with explicit task scope
  • Custom-agent versions are identified by profile-file Git commits
  • A new custom-agent task uses the latest profile for its selected repository and branch
  • Existing pull-request interactions retain the custom-agent version used to create the pull request
  • Profile-file identity and configuration scope determine which duplicate agent wins
  • Repository MCP settings can override a replacement worker's MCP configuration
  • Preserve the intended tool boundary when replacing an agent profile
  • A profile can load while environment-specific tool names are ignored
  • User selection and automatic invocation are independent agent lifecycle controls
  • A VS Code model list provides ordered availability fallback for a custom worker
  • Retire a custom agent through the source that supplies it
  • Inspect an agent's source before removing a similarly named configuration
  • Worktree-session archiving preserves branch changes before removing working files
  • Permanent session deletion requires preserving work first
  • Retiring one session does not remove a worktree still used by another session
  • Archived worker records require the appropriate session-list filter
  • Register SDK specialists in the session's customAgents configuration
  • Preserve explicitly configured skills when replacing an SDK worker
  • Archive cloud-agent sessions, because only local sessions can be deleted
  • Check prompt-file tool overrides when replacing a VS Code custom agent

Unlock with Premium — includes all practice exams and the complete study guide.