TypeScript
```typescript
import { CopilotClient } 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 and answers questions 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.",
},
],
onPermissionRequest: async () => ({ kind: "approve-once" }),
});
```
Python
```python
from copilot import CopilotClient, PermissionDecisionApproveOnce
client = CopilotClient()
await client.start()
session = await client.create_session(
on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),
model="gpt-5.4",
custom_agents=[
{
"name": "researcher",
"display_name": "Research Agent",
"description": "Explores codebases and answers questions 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",
"display_name": "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.",
},
],
)
```
Go
```golang
ctx := context.Background()
client := copilot.NewClient(nil)
client.Start(ctx)
session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
Model: "gpt-5.4",
CustomAgents: []copilot.CustomAgentConfig{
{
Name: "researcher",
DisplayName: "Research Agent",
Description: "Explores codebases and answers questions using read-only tools",
Tools: []string{"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: []string{"view", "edit", "bash"},
Prompt: "You are a code editor. Make minimal, surgical changes to files as requested.",
},
},
OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (rpc.PermissionDecision, error) {
return &rpc.PermissionDecisionApproveOnce{}, nil
},
})
```
.NET
```csharp
using GitHub.Copilot;
using GitHub.Copilot.Rpc;
await using var client = new CopilotClient();
await using var session = await client.CreateSessionAsync(new SessionConfig
{
Model = "gpt-5.4",
CustomAgents = new List
{
new()
{
Name = "researcher",
DisplayName = "Research Agent",
Description = "Explores codebases and answers questions using read-only tools",
Tools = new List { "grep", "glob", "view" },
Prompt = "You are a research assistant. Analyze code and answer questions. Do not modify any files.",
},
new()
{
Name = "editor",
DisplayName = "Editor Agent",
Description = "Makes targeted code changes",
Tools = new List { "view", "edit", "bash" },
Prompt = "You are a code editor. Make minimal, surgical changes to files as requested.",
},
},
OnPermissionRequest = (req, inv) =>
Task.FromResult(PermissionDecision.ApproveOnce()),
});
```
Java
```java
import com.github.copilot.CopilotClient;
import com.github.copilot.rpc.*;
import java.util.List;
try (var client = new CopilotClient()) {
client.start().get();
var session = client.createSession(
new SessionConfig()
.setModel("gpt-5.4")
.setCustomAgents(List.of(
new CustomAgentConfig()
.setName("researcher")
.setDisplayName("Research Agent")
.setDescription("Explores codebases and answers questions using read-only tools")
.setTools(List.of("grep", "glob", "view"))
.setPrompt("You are a research assistant. Analyze code and answer questions. Do not modify any files."),
new CustomAgentConfig()
.setName("editor")
.setDisplayName("Editor Agent")
.setDescription("Makes targeted code changes")
.setTools(List.of("view", "edit", "bash"))
.setPrompt("You are a code editor. Make minimal, surgical changes to files as requested.")
))
.setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
).get();
}
```
## Referência de configuração
| Property | Tipo | Obrigatório | Description |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ----------- | ------------------------------------- |
| `name` | `string` | ✅ | Identificador exclusivo para o agente |
| `displayName` | `string` | | |
| Nome legível por humanos exibido em eventos | | | |
| `description` | `string` | | |
| O que o agente faz — ajuda o runtime a selecioná-lo | | | |
| `tools` | | | |
| `string[]` ou `null` | | | |
| Nomes de ferramentas que o agente pode usar. | | | |
| `null` ou omitido = todas as ferramentas | | | |
| `prompt` | `string` | ✅ | Comando do sistema ao agente |
| `mcpServers` | `object` | | |
| Configurações de servidor MCP específicas para este agente | | | |
| `infer` | `boolean` | | |
| Se o runtime pode selecionar automaticamente este agente (padrão: `true`) | | | |
| `skills` | `string[]` | | |
| Nomes de habilidade a serem pré-carregados no contexto do agente na inicialização | | | |
| `model` | `string` | | |
| Identificador de modelo a ser usado enquanto este agente é executado | | | |
| `reasoningEffort` | `string` | | |
| Esforço de raciocínio a ser usado enquanto este agente estiver em execução. Quando omitido, o SDK não envia nenhuma substituição por agente e o runtime resolve o esforço (confira a observação abaixo) | | | |
> \[!TIP]
> Um bom `description` ajuda o runtime a corresponder a intenção do usuário com o agente certo. Seja específico sobre a experiência e as funcionalidades do agente.
Defina `model` e `reasoningEffort` para substituir as configurações do modelo da sessão pai enquanto um agente personalizado estiver em execução. Quando `reasoningEffort` é omitido, o SDK não envia nenhuma substituição específica por agente, e o runtime determina o esforço com base na própria ordem de precedência: uma opção do cliente por chamada, o padrão do modelo resolvido ou a definição do agente têm prioridade; caso contrário, o runtime herda o esforço da sessão pai somente quando o subagente usa o mesmo modelo que o pai. Quando o subagente passa a usar um modelo diferente, ele recorre ao padrão desse modelo em vez de herdar o esforço do agente pai. Python usa`reasoning_effort`, .NET usa`ReasoningEffort`, Go usa`ReasoningEffort`, Java usa `setReasoningEffort`e o Rust usa `with_reasoning_effort`.
Além da configuração por agente acima, você pode definir `agent` na própria **configuração da sessão** para selecionar previamente qual agente personalizado está ativo quando a sessão é iniciada. Veja [a seleção de um agente na criação da sessão](#selecting-an-agent-at-session-creation) abaixo.
| Propriedade de configuração da sessão | Tipo | Description |
| ------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |
| `agent` | `string` | Nome do agente personalizado a ser pré-selecionado na criação da sessão. Deve corresponder a um `name` em `customAgents`. |
## Habilidades por agente
Você pode pré-carregar habilidades no contexto de um agente usando a propriedade `skills`. Quando especificado, o **conteúdo completo** de cada habilidade listada é injetado ansiosamente no contexto do agente na inicialização– o agente não precisa invocar uma ferramenta de habilidade; as instruções já estão presentes. As habilidades são **aceitas**: os agentes não recebem habilidades por padrão, e os sub-agentes não herdam habilidades do pai. Os nomes de habilidade são resolvidos no nível da sessão `skillDirectories`.
```typescript
const session = await client.createSession({
skillDirectories: ["./skills"],
customAgents: [
{
name: "security-auditor",
description: "Security-focused code reviewer",
prompt: "Focus on OWASP Top 10 vulnerabilities",
skills: ["security-scan", "dependency-check"],
},
{
name: "docs-writer",
description: "Technical documentation writer",
prompt: "Write clear, concise documentation",
skills: ["markdown-lint"],
},
],
onPermissionRequest: async () => ({ kind: "approve-once" }),
});
```
Neste exemplo, `security-auditor` começa com `security-scan` e `dependency-check` já injetado em seu contexto, enquanto `docs-writer` começa com `markdown-lint`. Um agente sem um `skills` campo não recebe nenhum conteúdo de habilidade.
## Selecionando um agente na criação da sessão
Você pode passar `agent` na configuração da sessão para predefinir qual agente personalizado deverá ser ativado quando a sessão for iniciada. O valor deve corresponder ao `name` de um dos agentes definidos em `customAgents`.
Isso é equivalente à chamada `session.rpc.agent.select()` após a criação, mas evita a chamada extra à API e garante que o agente esteja ativo desde o primeiro prompt.
TypeScript
```typescript
const session = await client.createSession({
customAgents: [
{
name: "researcher",
prompt: "You are a research assistant. Analyze code and answer questions.",
},
{
name: "editor",
prompt: "You are a code editor. Make minimal, surgical changes.",
},
],
agent: "researcher", // Pre-select the researcher agent
});
```
Python
```python
session = await client.create_session(
on_permission_request=PermissionHandler.approve_all,
custom_agents=[
{
"name": "researcher",
"prompt": "You are a research assistant. Analyze code and answer questions.",
},
{
"name": "editor",
"prompt": "You are a code editor. Make minimal, surgical changes.",
},
],
agent="researcher", # Pre-select the researcher agent
)
```
Go
```golang
session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
CustomAgents: []copilot.CustomAgentConfig{
{
Name: "researcher",
Prompt: "You are a research assistant. Analyze code and answer questions.",
},
{
Name: "editor",
Prompt: "You are a code editor. Make minimal, surgical changes.",
},
},
Agent: "researcher", // Pre-select the researcher agent
})
```
.NET
```csharp
var session = await client.CreateSessionAsync(new SessionConfig
{
CustomAgents = new List
{
new() { Name = "researcher", Prompt = "You are a research assistant. Analyze code and answer questions." },
new() { Name = "editor", Prompt = "You are a code editor. Make minimal, surgical changes." },
},
Agent = "researcher", // Pre-select the researcher agent
});
```
Java
```java
import com.github.copilot.rpc.*;
import java.util.List;
var session = client.createSession(
new SessionConfig()
.setCustomAgents(List.of(
new CustomAgentConfig()
.setName("researcher")
.setPrompt("You are a research assistant. Analyze code and answer questions."),
new CustomAgentConfig()
.setName("editor")
.setPrompt("You are a code editor. Make minimal, surgical changes.")
))
.setAgent("researcher") // Pre-select the researcher agent
.setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
).get();
```
## Como funciona a delegação de subagente
Quando você envia um prompt para uma sessão com agentes personalizados, o runtime avalia se deseja delegar a um subagente:
1. **Correspondência de intenção** – o runtime analisa o prompt do usuário em relação a `name` e `description` de cada agente
2. **Seleção de agente**— Se uma correspondência for encontrada e `infer` não for `false`, o runtime selecionará o agente
3. **Execução isolada** – o sub-agente é executado com seu próprio prompt e conjunto de ferramentas restritas
4. **Transmissão de eventos** — eventos de ciclo de vida (`subagent.started`, `subagent.completed` etc.) são transmitidos de volta para a sessão pai
5. **Integração de resultados** – a saída do sub-agente é incorporada à resposta do agente pai
### Controlando a inferência
Por padrão, todos os agentes personalizados estão disponíveis para seleção automática (`infer: true`). Defina `infer: false` para impedir que o runtime selecione automaticamente um agente, útil para agentes que você só deseja invocar por meio de solicitações explícitas do usuário:
```typescript
{
name: "dangerous-cleanup",
description: "Deletes unused files and dead code",
tools: ["bash", "edit", "view"],
prompt: "You clean up codebases by removing dead code and unused files.",
infer: false, // Only invoked when user explicitly asks for this agent
}
```
## Escutar eventos de subagente
Quando um subagente é executado, a sessão pai emite eventos de ciclo de vida. Assine esses eventos para criar UIs que visualizam a atividade do agente.
Os eventos de sessão originados por subagentes compartilham o fluxo da sessão pai e incluem `agentId` no nível do envelope. Eventos do agente raiz/principal e eventos no nível da sessão omitem `agentId`, de modo que os renderizadores possam manter a resposta principal separada dos rastreamentos de subagentes ao verificar o envelope do evento.
### Tipos de evento
| Acontecimento | Emitido quando | Dados |
| -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | ----- |
| `subagent.selected` | O runtime seleciona um agente para a tarefa | |
| `agentName`, `agentDisplayName`, `tools` | | |
| `subagent.started` | Subagente inicia a execução | |
| `toolCallId`, `agentName`, `agentDisplayName`, , `agentDescription``model?` | | |
| `subagent.completed` | O subagente foi concluído com êxito | |
| `toolCallId`, `agentName`, `agentDisplayName`, `model?`, , `durationMs?`, `totalTokens?`, `totalToolCalls?` | | |
| `subagent.failed` | O subagente encontra um erro | |
| `toolCallId`, `agentName`, `agentDisplayName`, `error`, `model?`, `durationMs?`, `totalTokens?`, , `totalToolCalls?` | | |
| `subagent.deselected` | O runtime muda seu foco do subagente | — |
### Inscrevendo-se para eventos
TypeScript
```typescript
session.on((event) => {
switch (event.type) {
case "subagent.started":
console.log(`▶ Sub-agent started: ${event.data.agentDisplayName}`);
console.log(` Description: ${event.data.agentDescription}`);
console.log(` Tool call ID: ${event.data.toolCallId}`);
break;
case "subagent.completed":
console.log(`✅ Sub-agent completed: ${event.data.agentDisplayName}`);
if (event.data.durationMs !== undefined) console.log(` Duration: ${event.data.durationMs}ms`);
if (event.data.totalTokens !== undefined) console.log(` Tokens: ${event.data.totalTokens}`);
if (event.data.totalToolCalls !== undefined) console.log(` Tool calls: ${event.data.totalToolCalls}`);
break;
case "subagent.failed":
console.log(`❌ Sub-agent failed: ${event.data.agentDisplayName}`);
console.log(` Error: ${event.data.error}`);
if (event.data.durationMs !== undefined) console.log(` Duration: ${event.data.durationMs}ms`);
break;
case "subagent.selected":
console.log(`🎯 Agent selected: ${event.data.agentDisplayName}`);
console.log(` Tools: ${event.data.tools?.join(", ") ?? "all"}`);
break;
case "subagent.deselected":
console.log("↩ Agent deselected, returning to parent");
break;
}
});
const response = await session.sendAndWait({
prompt: "Research how authentication works in this codebase",
});
```
Python
```python
def handle_event(event):
if event.type == "subagent.started":
print(f"▶ Sub-agent started: {event.data.agent_display_name}")
print(f" Description: {event.data.agent_description}")
elif event.type == "subagent.completed":
print(f"✅ Sub-agent completed: {event.data.agent_display_name}")
elif event.type == "subagent.failed":
print(f"❌ Sub-agent failed: {event.data.agent_display_name}")
print(f" Error: {event.data.error}")
elif event.type == "subagent.selected":
tools = event.data.tools or "all"
print(f"🎯 Agent selected: {event.data.agent_display_name} (tools: {tools})")
unsubscribe = session.on(handle_event)
response = await session.send_and_wait("Research how authentication works in this codebase")
```
Go
```golang
session.On(func(event copilot.SessionEvent) {
switch d := event.Data.(type) {
case *copilot.SubagentStartedData:
fmt.Printf("▶ Sub-agent started: %s\n", d.AgentDisplayName)
fmt.Printf(" Description: %s\n", d.AgentDescription)
fmt.Printf(" Tool call ID: %s\n", d.ToolCallID)
case *copilot.SubagentCompletedData:
fmt.Printf("✅ Sub-agent completed: %s\n", d.AgentDisplayName)
case *copilot.SubagentFailedData:
fmt.Printf("❌ Sub-agent failed: %s — %v\n", d.AgentDisplayName, d.Error)
case *copilot.SubagentSelectedData:
fmt.Printf("🎯 Agent selected: %s\n", d.AgentDisplayName)
}
})
_, err := session.SendAndWait(ctx, copilot.MessageOptions{
Prompt: "Research how authentication works in this codebase",
})
```
.NET
```csharp
using var subscription = session.On
(evt =>
{
switch (evt)
{
case SubagentStartedEvent started:
Console.WriteLine($"▶ Sub-agent started: {started.Data.AgentDisplayName}");
Console.WriteLine($" Description: {started.Data.AgentDescription}");
Console.WriteLine($" Tool call ID: {started.Data.ToolCallId}");
break;
case SubagentCompletedEvent completed:
Console.WriteLine($"✅ Sub-agent completed: {completed.Data.AgentDisplayName}");
break;
case SubagentFailedEvent failed:
Console.WriteLine($"❌ Sub-agent failed: {failed.Data.AgentDisplayName} — {failed.Data.Error}");
break;
case SubagentSelectedEvent selected:
Console.WriteLine($"🎯 Agent selected: {selected.Data.AgentDisplayName}");
break;
}
});
await session.SendAndWaitAsync(new MessageOptions
{
Prompt = "Research how authentication works in this codebase"
});
```
Java
```java
session.on(event -> {
if (event instanceof SubagentStartedEvent e) {
System.out.println("▶ Sub-agent started: " + e.getData().agentDisplayName());
System.out.println(" Description: " + e.getData().agentDescription());
System.out.println(" Tool call ID: " + e.getData().toolCallId());
} else if (event instanceof SubagentCompletedEvent e) {
System.out.println("✅ Sub-agent completed: " + e.getData().agentName());
} else if (event instanceof SubagentFailedEvent e) {
System.out.println("❌ Sub-agent failed: " + e.getData().agentName());
System.out.println(" Error: " + e.getData().error());
} else if (event instanceof SubagentSelectedEvent e) {
System.out.println("🎯 Agent selected: " + e.getData().agentDisplayName());
} else if (event instanceof SubagentDeselectedEvent e) {
System.out.println("↩ Agent deselected, returning to parent");
}
});
var response = session.sendAndWait(
new MessageOptions().setPrompt("Research how authentication works in this codebase")
).get();
```
## Construir uma interface de usuário de árvore de agente
Eventos de subagente incluem campos `toolCallId` que permitem reconstruir a árvore de execução. Aqui está um padrão para acompanhar a atividade do agente:
```typescript
interface AgentNode {
toolCallId: string;
name: string;
displayName: string;
status: "running" | "completed" | "failed";
error?: string;
startedAt: Date;
completedAt?: Date;
}
const agentTree = new Map