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

> Learn to create and configure custom Copilot SDK agents with specific tools and instructions. Define agent configurations and integrate them seamlessly.

- Repository: [GitHub/copilot-sdk](https://github.com/github/copilot-sdk)
- Tags: how-to-guide
- Published: 2026-08-02

---

**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`:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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`](https://github.com/github/copilot-sdk/blob/main/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`](https://github.com/github/copilot-sdk/blob/main/docs/features/custom-agents.md).