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();
}
```
## Referencia de configuración
| Propiedad | Tipo | Obligatorio | Description |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ----------- | ------------------------------------- |
| `name` | `string` | ✅ | Identificador único del agente |
| `displayName` | `string` | | |
| Nombre comprensible que se muestra en eventos | | | |
| `description` | `string` | | |
| Lo que hace el agente: ayuda al tiempo de ejecución a seleccionarlo. | | | |
| `tools` | | | |
| `string[]` o `null` | | | |
| Nombres de herramienta que el agente puede usar. | | | |
| `null` o se omite = todas las herramientas | | | |
| `prompt` | `string` | ✅ | Indicativo del sistema para el agente |
| `mcpServers` | `object` | | |
| Configuraciones de servidor MCP específicas de este agente | | | |
| `infer` | `boolean` | | |
| Si el entorno de ejecución puede seleccionar automáticamente este agente (valor predeterminado: `true`) | | | |
| `skills` | `string[]` | | |
| Nombres de las aptitudes que se cargarán previamente en el contexto del agente al iniciarse | | | |
| `model` | `string` | | |
| Identificador de modelo que se va a usar mientras se ejecuta este agente | | | |
| `reasoningEffort` | `string` | | |
| Esfuerzo de razonamiento que se debe utilizar mientras se ejecuta este agente. Si se omite, el SDK no envía ninguna anulación por agente y el tiempo de ejecución resuelve el esfuerzo (véase la nota más abajo) | | | |
> \[!TIP]
> Una buena `description` ayuda al entorno de ejecución a coincidir la intención del usuario con el agente correcto. Sea específico sobre la experiencia y las funcionalidades del agente.
Establezca `model` y `reasoningEffort` para invalidar la configuración del modelo de la sesión primaria mientras se ejecuta un agente personalizado. Cuando se omite `reasoningEffort`, el SDK no envía ninguna anulación por agente y el entorno de ejecución determina el esfuerzo según su propio orden de precedencia: una opción de cliente para esa llamada, el valor predeterminado del modelo resuelto o la definición del agente tienen prioridad; de lo contrario, el entorno de ejecución hereda el esfuerzo de la sesión principal solo cuando el subagente ejecuta el mismo modelo que el principal. Cuando el subagente se resuelve en un modelo diferente, recurre al valor predeterminado de ese modelo en lugar de heredar el esfuerzo del padre. Python usa `reasoning_effort`, .NET usa `ReasoningEffort`, Go usa `ReasoningEffort`, Java usa `setReasoningEffort`y Rust usa `with_reasoning_effort`.
Además de la configuración por agente anterior, puede establecer `agent` en la **propia configuración de sesión** para seleccionar previamente qué agente personalizado está activo cuando se inicia la sesión. Consulte [Selección de un agente en la creación de la sesión](#selecting-an-agent-at-session-creation) a continuación.
| Propiedad de configuración de sesión | Tipo | Description |
| ------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `agent` | `string` | Nombre del agente personalizado que se va a seleccionar previamente en la creación de la sesión. Debe coincidir con un `name` en `customAgents`. |
## Aptitudes por agente
Puede cargar previamente aptitudes en el contexto de un agente mediante la propiedad `skills`. Cuando se especifica, el **contenido completo** de cada aptitud enumerada se inserta diligentemente en el contexto del agente al iniciarse; el agente no necesita invocar una herramienta de aptitud; las instrucciones ya están presentes. Las aptitudes son **opcionales**: los agentes no reciben aptitudes de forma predeterminada y los subagentes no heredan las aptitudes del elemento primario. Los nombres de las aptitudes se resuelven a partir de `skillDirectories` de nivel de sesión.
```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" }),
});
```
En este ejemplo, `security-auditor` comienza con `security-scan` y `dependency-check` ya insertado en su contexto, mientras que `docs-writer` comienza con `markdown-lint`. Un agente sin un `skills` campo no recibe contenido de aptitudes.
## Selección de un agente al crear la sesión
Puede introducir `agent` en la configuración de la sesión para preseleccionar qué agente personalizado estará activo cuando la sesión comience. El valor debe coincidir con el `name` de uno de los agentes definidos en `customAgents`.
Esto equivale a llamar `session.rpc.agent.select()` después de la creación, pero evita la llamada API adicional y garantiza que el agente está activo desde el primer aviso.
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();
```
## Funcionamiento de la delegación de subagentes
Cuando se envía una solicitud a una sesión con agentes personalizados, el tiempo de ejecución evalúa si se va a delegar en un subagente:
1. **Coincidencia de intenciones**: el tiempo de ejecución analiza el mensaje del usuario con respecto a los agentes `name` y `description`
2. **Selección del agente**: si se encuentra una coincidencia y `infer` no es `false`, el tiempo de ejecución selecciona al agente.
3. **Ejecución aislada**: el subagente se ejecuta con su propio símbolo del sistema y un conjunto de herramientas restringido
4. **Transmisión de eventos**: los eventos de ciclo de vida (`subagent.started`, `subagent.completed`, etc.) vuelven a la sesión principal.
5. **Integración de resultados**: la salida del subagente se incorpora a la respuesta del agente principal.
### Control de la inferencia
De forma predeterminada, todos los agentes personalizados están disponibles para la selección automática (`infer: true`). Establézcalo `infer: false` para impedir que el tiempo de ejecución seleccione automáticamente un agente, útil para los agentes que solo desea invocar a través de solicitudes de usuario explícitas:
```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
}
```
## Escuchando eventos del subagente
Cuando se ejecuta un subagente, la sesión primaria emite eventos de ciclo de vida. Suscríbase a estos eventos para crear interfaces de usuario que visualicen la actividad del agente.
Los eventos de sesión originados por subagentes comparten el flujo de sesión del padre e incluyen `agentId` en el nivel de sobre. Los eventos del agente raíz/principal y los eventos de nivel de sesión omiten `agentId`, por lo que los renderizadores pueden mantener la respuesta del agente padre separada de las trazas del subagente verificando el sobre del evento.
### Tipos de evento
| Event | Emitido cuando | Data |
| ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------- | ---- |
| `subagent.selected` | Runtime selecciona un agente para la tarea. | |
| `agentName`, , `agentDisplayName`, `tools` | | |
| `subagent.started` | El subagente inicia la ejecución | |
| `toolCallId`, `agentName`, `agentDisplayName`, , `agentDescription`, `model?` | | |
| `subagent.completed` | El subagente finaliza correctamente | |
| `toolCallId`, `agentName`, `agentDisplayName`, `model?`, `durationMs?`, , `totalTokens?``totalToolCalls?` | | |
| `subagent.failed` | Subagente encuentra un error | |
| `toolCallId`, `agentName`, `agentDisplayName`, `error`, `model?`, `durationMs?`, , `totalTokens?``totalToolCalls?` | | |
| `subagent.deselected` | Tiempo de ejecución se aleja del subagente | — |
### Suscribirse a 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();
```
## Creación de una interfaz de usuario de árbol de agente
Los eventos de subagente incluyen `toolCallId` campos que permiten reconstruir el árbol de ejecución. Este es un patrón para realizar el seguimiento de la actividad del agente:
```typescript
interface AgentNode {
toolCallId: string;
name: string;
displayName: string;
status: "running" | "completed" | "failed";
error?: string;
startedAt: Date;
completedAt?: Date;
}
const agentTree = new Map