How to Create and Configure Custom Agents with Specific Tools and Instructions in the Copilot SDK

You create custom agents in the Copilot SDK by defining a CustomAgentConfig object with a unique name, system prompt, and optional tool whitelist, then passing an array of these configurations to the customAgents parameter when calling client.createSession().

The GitHub Copilot SDK enables developers to create and configure custom agents with specific tools and instructions, allowing you to deploy specialized AI personas that handle distinct tasks within isolated contexts. By defining agent configurations in TypeScript and passing them during session initialization, you can control exactly which tools each agent accesses and how the runtime selects them. This guide covers the complete implementation based on the official github/copilot-sdk source code.

Understanding the CustomAgentConfig Interface

All custom agent definitions follow the CustomAgentConfig interface located in nodejs/src/types.ts#L1691:

export interface CustomAgentConfig {
  name: string;                     // required
  displayName?: string;             // optional human name
  description?: string;             // optional description used for inference
  tools?: string[] | null;          // tool whitelist (null = all)
  prompt: string;                   // required system prompt
  mcpServers?: Record<string, McpServerConfig>;
  infer?: boolean;                  // default true
  skills?: string[];
  model?: string;
  reasoningEffort?: string;
}

Required Fields

Every custom agent must specify a name (unique identifier used for selection) and a prompt (system message that defines the agent's behavior and constraints).

Optional Configuration Fields

• tools: An array of tool names the agent may call (e.g., ["grep", "view"]). When omitted or set to null, the agent can access all available tools.
• infer: Controls auto-selection behavior. Set to false to prevent the runtime from automatically selecting this agent based on the user's prompt.
• mcpServers: Attaches Model Context Protocol (MCP) servers scoped specifically to this agent.
• model and reasoningEffort: Override the default model or reasoning level for this specific agent.

Implementing Custom Agents in TypeScript

When you create a session, the SDK serializes your agent configurations using toWireCustomAgents (found in nodejs/src/client.ts#L248) before transmitting them via JSON-RPC.

Basic Agent Setup with Tool Restrictions

Define multiple agents with distinct toolsets to enforce least-privilege access:

import { CopilotClient, approveAll } from "@github/copilot-sdk";

const client = new CopilotClient();
await client.start();

const session = await client.createSession({
  model: "gpt-5.4",
  customAgents: [
    {
      name: "researcher",
      displayName: "Research Agent",
      description: "Explores codebases using read-only tools",
      tools: ["grep", "glob", "view"],
      prompt: "You are a research assistant. Analyze code and answer questions. Do not modify any files.",
    },
    {
      name: "editor",
      displayName: "Editor Agent",
      description: "Makes targeted code changes",
      tools: ["view", "edit", "bash"],
      prompt: "You are a code editor. Make minimal, surgical changes to files as requested.",
    },
  ],
  agent: "researcher",
  onPermissionRequest: approveAll,
});

await session.send({ prompt: "Search for TODO comments in the repo." });

The agent field pre-selects the "researcher" agent, while each agent's tools whitelist restricts what it can invoke; the editor can call edit while the researcher cannot.

Explicit Agent Selection vs. Auto-Inference

To prevent the runtime from auto-selecting an agent, set infer: false and manually trigger the agent via RPC:

const session = await client.createSession({
  model: "gpt-5.4",
  customAgents: [
    {
      name: "security-auditor",
      description: "Security-focused code reviewer",
      tools: ["grep", "view"],
      infer: false,
      prompt: "Identify security vulnerabilities in code.",
    },
  ],
});

await session.rpc.agent.select({ name: "security-auditor" });
await session.send({ prompt: "Audit the recent pull request for XSS issues." });

Advanced Configuration with MCP Servers and Model Overrides

Attach dedicated MCP servers and override the base model for specific agents:

const session = await client.createSession({
  model: "gpt-5.4",
  customAgents: [
    {
      name: "data-inspector",
      description: "Runs queries against a private database",
      tools: ["mcp:data-db"],
      mcpServers: {
        "data-db": {
          url: "https://my-db.example.com",
          token: process.env.DB_TOKEN,
        },
      },
      model: "claude-3.5-sonnet",
      prompt: "You are a data analyst with access to a secure DB.",
    },
  ],
});

Runtime Behavior and Lifecycle

According to the github/copilot-sdk source code and documentation in docs/features/custom-agents.md, the runtime processes custom agents through the following lifecycle:

1. Session Initialization: The client sends the customAgents array during createSession, serialized by toWireCustomAgents in nodejs/src/client.ts#L248.
2. Inference Phase: For each user prompt, the runtime evaluates agent description fields and available tools to determine the best match.
3. Sub-Agent Isolation: When selected, the agent runs as a sub-agent with its own isolated context, restricted to its whitelisted tools.
4. Event Streaming: The parent session receives lifecycle events including agent.select, agent.completed, and tool execution streams from the sub-agent.

Summary

• Define custom agents using the CustomAgentConfig interface, requiring at minimum a name and prompt.
• Pass agent configurations via the customAgents array in client.createSession().
• Restrict agent capabilities using the tools field to implement security boundaries.
• Set infer: false to disable auto-selection and use session.rpc.agent.select() for explicit activation.
• Attach per-agent MCP servers via mcpServers and override models using the model field.

Frequently Asked Questions

What is the minimum configuration required to create a custom agent in the Copilot SDK?

The minimum configuration requires a name (unique identifier) and a prompt (system instructions). All other fields in CustomAgentConfig are optional, though specifying tools is recommended to limit agent capabilities.

How do I prevent the Copilot SDK runtime from automatically selecting my custom agent?

Set the infer property to false in your CustomAgentConfig. This prevents the runtime's inference engine from auto-selecting the agent based on the user's prompt, requiring you to explicitly activate it using session.rpc.agent.select({ name: "agent-name" }).

Can different custom agents use different AI models within the same session?

Yes. You can override the default model for any agent by specifying the model field in its configuration. For example, you can run the main session on gpt-5.4 while configuring a specific agent to use claude-3.5-sonnet for specialized tasks.

Where are custom agent configurations defined in the Copilot SDK source code?

The TypeScript interface CustomAgentConfig is defined in nodejs/src/types.ts#L1691, and the serialization logic resides in nodejs/src/client.ts#L248 within the toWireCustomAgents function. Additional implementation details and examples are available in docs/features/custom-agents.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}