Agentes personalizados y orquestación de subagentes

          SDK de Copilot actualmente está en Versión preliminar técnica. La funcionalidad y la disponibilidad están sujetas a cambios.

Los agentes personalizados son definiciones de agente ligeras que se adjuntan a una sesión. Cada agente tiene su propia solicitud del sistema, restricciones de herramientas y servidores MCP opcionales. Cuando la solicitud de un usuario coincide con la experiencia de un agente, el SDK de Copilot entorno de ejecución se delega automáticamente en ese agente como subagente, ejecutándolo en un contexto aislado mientras transmite eventos del ciclo de vida a la sesión principal. Para obtener información general visual sobre el flujo de delegación, consulte el github/copilot-sdk repositorio.

Concepto	Descripción

          **Agente personalizado** | Configuración de agente nombrada con su propio indicador y conjunto de herramientas |

| Subagente | Un agente personalizado invocado por el tiempo de ejecución para controlar parte de una tarea | | Inferencia | La capacidad del tiempo de ejecución para seleccionar automáticamente un agente en función de la intención del usuario | | Sesión principal | Sesión que generó el subagente; recibe todos los eventos del ciclo de vida. |

Definición de agentes personalizados

Pase customAgents al crear una sesión. Como mínimo, cada agente necesita un name y un prompt.

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

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

const session = await client.createSession({
    model: "gpt-4.1",
    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: "approved" }),
});

Para obtener ejemplos en Python, Go y .NET, consulte el github/copilot-sdk repositorio.

Referencia de configuración

Propiedad	Tipo	Obligatorio	Descripción
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 herramientas que puede usar el agente. 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) |

Además de la configuración por agente, puede establecer agent en la configuración de sesión para seleccionar previamente qué agente personalizado está activo cuando se inicia la sesión.

Propiedad de configuración de sesión	Tipo	Descripción
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.

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.

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
});

Para obtener ejemplos en Python, Go y .NET, consulte el github/copilot-sdk repositorio.

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:

{
    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.

Tipos de evento

Event	Emitido cuando	Datos
subagent.selected	Runtime selecciona un agente para la tarea.

          `agentName`, , `agentDisplayName`, `tools` |

| subagent.started | El subagente inicia la ejecución | toolCallId, agentName, , agentDisplayName, agentDescription | | subagent.completed | El subagente finaliza correctamente | toolCallId, , agentName, agentDisplayName | | subagent.failed | Subagente encuentra un error | toolCallId, agentName, , agentDisplayName, error | | subagent.deselected | Tiempo de ejecución se aleja del subagente | — |

Suscribirse a eventos

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}`);
            break;

        case "subagent.failed":
            console.log(`❌ Sub-agent failed: ${event.data.agentDisplayName}`);
            console.log(`  Error: ${event.data.error}`);
            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",
});

Para obtener ejemplos en Python, Go y .NET, consulte el github/copilot-sdk repositorio.

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:

interface AgentNode {
    toolCallId: string;
    name: string;
    displayName: string;
    status: "running" | "completed" | "failed";
    error?: string;
    startedAt: Date;
    completedAt?: Date;
}

const agentTree = new Map<string, AgentNode>();

session.on((event) => {
    if (event.type === "subagent.started") {
        agentTree.set(event.data.toolCallId, {
            toolCallId: event.data.toolCallId,
            name: event.data.agentName,
            displayName: event.data.agentDisplayName,
            status: "running",
            startedAt: new Date(event.timestamp),
        });
    }

    if (event.type === "subagent.completed") {
        const node = agentTree.get(event.data.toolCallId);
        if (node) {
            node.status = "completed";
            node.completedAt = new Date(event.timestamp);
        }
    }

    if (event.type === "subagent.failed") {
        const node = agentTree.get(event.data.toolCallId);
        if (node) {
            node.status = "failed";
            node.error = event.data.error;
            node.completedAt = new Date(event.timestamp);
        }
    }

    // Render your UI with the updated tree
    renderAgentTree(agentTree);
});

Herramientas de definición por agente

Use la tools propiedad para restringir las herramientas a las que puede acceder un agente. Esto es esencial para la seguridad y para mantener los agentes centrados:

const session = await client.createSession({
    customAgents: [
        {
            name: "reader",
            description: "Read-only exploration of the codebase",
            tools: ["grep", "glob", "view"],  // No write access
            prompt: "You explore and analyze code. Never suggest modifications directly.",
        },
        {
            name: "writer",
            description: "Makes code changes",
            tools: ["view", "edit", "bash"],   // Write access
            prompt: "You make precise code changes as instructed.",
        },
        {
            name: "unrestricted",
            description: "Full access agent for complex tasks",
            tools: null,                        // All tools available
            prompt: "You handle complex multi-step tasks using any available tools.",
        },
    ],
});

Adjuntar servidores MCP a agentes

Cada agente personalizado puede tener sus propios servidores MCP (Protocolo de contexto de modelo), lo que le proporciona acceso a orígenes de datos especializados:

const session = await client.createSession({
    customAgents: [
        {
            name: "db-analyst",
            description: "Analyzes database schemas and queries",
            prompt: "You are a database expert. Use the database MCP server to analyze schemas.",
            mcpServers: {
                "database": {
                    command: "npx",
                    args: ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"],
                },
            },
        },
    ],
});

Patrones y procedimientos recomendados

Emparejar un investigador con un editor

Un patrón común es definir un agente investigador de solo lectura y un agente editor capaz de escritura. El tiempo de ejecución delega las tareas de exploración al investigador y las tareas de modificación al editor:

customAgents: [
    {
        name: "researcher",
        description: "Analyzes code structure, finds patterns, and answers questions",
        tools: ["grep", "glob", "view"],
        prompt: "You are a code analyst. Thoroughly explore the codebase to answer questions.",
    },
    {
        name: "implementer",
        description: "Implements code changes based on analysis",
        tools: ["view", "edit", "bash"],
        prompt: "You make minimal, targeted code changes. Always verify changes compile.",
    },
]

Mantener las descripciones del agente específicas

El tiempo de ejecución usa el description para que coincida con la intención del usuario. Las descripciones vagas conducen a una delegación deficiente:

// ❌ Too vague — runtime can't distinguish from other agents
{ description: "Helps with code" }

// ✅ Specific — runtime knows when to delegate
{ description: "Analyzes Python test coverage and identifies untested code paths" }

Gestiona los fallos de manera elegante

Los subagentes pueden fallar. Escuche siempre los eventos de subagent.failed y manéjelos en su aplicación.

session.on((event) => {
    if (event.type === "subagent.failed") {
        logger.error(`Agent ${event.data.agentName} failed: ${event.data.error}`);
        // Show error in UI, retry, or fall back to parent agent
    }
});