---
title: Orquestación multiagente
url: https://platform.claude.com/docs/es/managed-agents/multiagent-orchestration
description: Coordina múltiples agentes dentro de una sola sesión.
featureMetadata:
topic:
title: Managed Agents
url: https://platform.claude.com/docs/en/managed-agents/overview
status: beta
betaHeader: managed-agents-2026-04-01
---
La orquestación multiagente permite que un agente se coordine con otros para completar trabajo complejo. Los agentes pueden actuar en paralelo con su propio contexto aislado, lo que ayuda a mejorar la calidad de la salida y también puede reducir el tiempo de finalización.
¿No estás seguro de si una configuración multiagente se ajusta a tu problema? Consulta [cuándo usar sistemas multiagente (y cuándo no)](https://claude.com/blog/building-multi-agent-systems-when-and-how-to-use-them).
## Delegar trabajo a otros agentes
El agente que ejecuta una sesión puede delegar trabajo a otros agentes de dos maneras. Con los **subagents** (subagentes), delega tareas por sí mismo y lee lo que informa cada subagente. Con los **dynamic workflows** (flujos de trabajo dinámicos), escribe un flujo de trabajo: un programa que ejecuta muchos agentes en segundo plano y combina sus resultados. También puede consultar a un modelo **advisor** (asesor) para obtener orientación mientras hace el trabajo por sí mismo.
Tú decides cuáles de estos puede usar el agente, y el agente determina cuándo usarlos. Para orientar esa elección, indícale al agente en su indicación del sistema cuándo usar una ejecución de flujo de trabajo. Consulta [Indicarle al agente cuándo usar una ejecución](https://platform.claude.com/docs/es/managed-agents/multiagent-orchestration#tell-the-agent-when-to-use-a-run). También puedes limitar al agente a los agentes que enumeres.
Con los subagentes, el propio agente determina qué sucede a continuación. El [hilo de un subagente](https://platform.claude.com/docs/es/managed-agents/session-threads) permanece disponible hasta que lo archives, por lo que el agente puede enviarle mensajes de seguimiento. Con los flujos de trabajo dinámicos, Claude escribe un programa para orquestar agentes sin la participación directa de Claude. El contexto y los resultados se pasan programáticamente de un agente a otro, lo que libera el hilo principal de la sesión para comunicarse con el usuario y revisar uno o varios flujos de trabajo en ejecución para informar sobre su progreso. El agente no puede enviar mensajes de seguimiento a los hilos de una ejecución, y el servidor archiva cada uno al final de su ejecución.
| Enfoque | Qué sucede | Úsalo cuando | Ten en cuenta |
| -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Subagentes](https://platform.claude.com/docs/es/managed-agents/multiagent-orchestration#delegate-to-subagents) | El agente delega tareas a sus subagentes. Cada subagente trabaja en su propio [hilo de sesión](https://platform.claude.com/docs/es/managed-agents/session-threads), que puedes listar y transmitir por streaming. | El agente debe hacer seguimiento con un subagente después de que este informe, o necesita especialistas que tú enumeras, con sus propias indicaciones del sistema y herramientas. | La delegación tiene un solo nivel de profundidad, y una sesión puede tener como máximo 25 hilos hijos a la vez, incluidos los inactivos. Los hilos del asesor y los hilos de una ejecución de flujo de trabajo no cuentan. |
| [Flujos de trabajo dinámicos](https://platform.claude.com/docs/es/managed-agents/multiagent-orchestration#dynamic-workflows) | El agente escribe un flujo de trabajo: un programa que ejecuta muchos agentes en fases y combina sus resultados. El servidor lo ejecuta en segundo plano como una ejecución de flujo de trabajo, que puedes seguir. El flujo de trabajo define los agentes o los elige de una lista que tú proporcionas. | La mayoría del trabajo que necesita más de un agente: trabajo con muchas partes, trabajo en paralelo o una tarea larga que debería terminar antes. Algunos ejemplos son auditorías, migraciones, investigación profunda y verificación cruzada. | Cada agente de una ejecución consume tokens, así que establece un [presupuesto de sesión](https://platform.claude.com/docs/es/managed-agents/budgets) para limitar el gasto de la sesión, incluidas las ejecuciones. Indícale al agente en su indicación del sistema cuándo usar una ejecución. Sigues la ejecución por sus fases y puedes leer cada uno de sus hilos. |
| [Darle un asesor a la sesión](https://platform.claude.com/docs/es/managed-agents/multiagent-orchestration#give-the-session-an-advisor) | El [hilo principal](https://platform.claude.com/docs/es/managed-agents/multiagent-orchestration#how-it-works) de la sesión consulta a un modelo asesor a mitad de turno para obtener orientación, como planificar un enfoque o revisar el trabajo, y sigue haciendo el trabajo por sí mismo. | Un solo agente debe hacer el trabajo, con el criterio de un modelo asesor en momentos clave, como la planificación o una revisión final. | Solo el hilo principal puede consultar al asesor, y las consultas se facturan según las tarifas del modelo asesor. |
Configuras esto en el bloque `multiagent` de la definición del agente, que tiene un `type`. Con el tipo `multiagent_20261001`, un agente puede usar los tres a la vez, y puedes activar o desactivar cada uno. De forma predeterminada, `subagents` y `workflows` están habilitados. `subagents` y `workflows` tienen cada uno `inline_agents` habilitado, la configuración para [agentes que el propio agente o un flujo de trabajo define](https://platform.claude.com/docs/es/managed-agents/multiagent-orchestration#predefined-and-inline-agents):
```json
{
"multiagent": { "type": "multiagent_20261001" }
}
```
Para establecer a qué agentes puede llamar el agente, consulta [Agentes predefinidos e inline](https://platform.claude.com/docs/es/managed-agents/multiagent-orchestration#predefined-and-inline-agents). Para desactivar una configuración, consulta [Activar los flujos de trabajo dinámicos](https://platform.claude.com/docs/es/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows).
## Agentes predefinidos e inline
Cada subagente, y cada agente de una ejecución de flujo de trabajo, es de uno de dos tipos:
* **Agente predefinido:** Un agente que ya has [creado](https://platform.claude.com/docs/es/managed-agents/agent-setup) y que enumeras en el bloque `multiagent` (csharp, go: `Multiagent`). Usa su propia configuración: modelo, indicación del sistema, herramientas, servidores MCP y skills.
* **Agente inline:** Un agente que no está guardado. El agente que ejecuta la sesión, o un flujo de trabajo, lo define cuando reparte el trabajo. Usa el modelo, las herramientas, los servidores MCP y las skills de ese agente.
Ambos tipos funcionan bajo `subagents` y bajo `workflows`:
| Tipo de agente | Bajo `subagents` | Bajo `workflows` |
| -------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Predefinido | El agente puede delegar a los agentes que enumeras en `subagents.predefined_agents`. | Un flujo de trabajo puede usar los agentes que enumeras en `workflows.predefined_agents`. |
| Inline | El agente puede definir un agente inline cuando delega. `subagents.inline_agents` activa o desactiva esto. | Un flujo de trabajo puede definir agentes inline, y escribe una indicación del sistema para cada uno. `workflows.inline_agents` activa o desactiva esto. |
`subagents.predefined_agents` y `workflows.predefined_agents` son dos listas separadas. Un agente de una lista no se agrega a la otra. Ambas listas están vacías de forma predeterminada. Una entrada de cualquiera de las listas adopta una de estas formas:
* `{"type": "agent", "id": agent.id}` hace referencia a un `agent` creado previamente por su ID. Si no se especifica `version`, la referencia se fija a la versión más reciente del agente cuando se crea el agente que lo enumera, o cuando una actualización envía la lista.
* `{"type": "agent", "id": agent.id, "version": agent.version}` fija una versión específica del agente.
* `agent.id` por sí solo, como cadena, es una forma abreviada de `{"type": "agent", "id": agent.id}`.
* `{"type": "self"}` enumera al propio agente, para que copias de él puedan hacer el trabajo. Si la sesión se creó con [anulaciones de configuración del agente](https://platform.claude.com/docs/es/managed-agents/sessions#override-agent-configuration-for-a-session), esas anulaciones también se aplican a estas copias. Las entradas referenciadas por ID no se ven afectadas.
Las reglas para estas entradas, y para los agentes que nombran, se aplican a ambas listas. Consulta [Enumerar los subagentes](https://platform.claude.com/docs/es/managed-agents/multiagent-orchestration#list-the-subagents).
Los agentes inline están activados de forma predeterminada en ambas configuraciones. Para permitir solo los agentes que enumeras, establece `inline_agents` en `{"type": "disabled"}` bajo `subagents`, bajo `workflows` o bajo ambos. Una configuración con los agentes inline desactivados necesita al menos un agente en su lista `predefined_agents`. Con una lista vacía, la solicitud falla con un error 400. En una actualización, el servidor verifica la configuración tal como queda después de la actualización.
El siguiente agente permite solo los agentes que enumera. Puede delegar a un agente y a copias de sí mismo, y un flujo de trabajo puede usar la versión 2 de otro agente:
```json
{
"multiagent": {
"type": "multiagent_20261001",
"subagents": {
"type": "enabled",
"inline_agents": { "type": "disabled" },
"predefined_agents": ["agent_01J8XkN5uT3vHpLqRfWdY2", { "type": "self" }]
},
"workflows": {
"type": "enabled",
"inline_agents": { "type": "disabled" },
"predefined_agents": [
{ "type": "agent", "id": "agent_01Lm4cV8yQ2tNs7XbKdR5h", "version": 2 }
]
}
}
}
```
## Delegar a subagentes
### Qué delegar
La coordinación multiagente es más adecuada para tareas complejas que requieren trabajo en una variedad de superficies, o en las que varias tareas bien delimitadas contribuyen a un objetivo general.
Patrones que funcionan bien:
* **Paralelización:** Distribuye subtareas independientes simultáneamente (buscar en varias fuentes, analizar archivos separados) y haz que el agente sintetice los resultados.
* **Especialización:** Dirige el trabajo a agentes con indicaciones del sistema y herramientas enfocadas en un dominio, como un agente de seguridad o un agente de documentación, en lugar de cargar a un solo agente con todas las capacidades.
* **Escalamiento:** Consulta a un agente o modelo más capaz para un subconjunto de subtareas complejas. Para consultar a un modelo, [dale un asesor a la sesión](https://platform.claude.com/docs/es/managed-agents/multiagent-orchestration#give-the-session-an-advisor).
### Cómo funciona
Todos los agentes comparten el mismo sandbox, sistema de archivos y [credenciales de vault](https://platform.claude.com/docs/es/managed-agents/vaults), pero cada agente se ejecuta en su propio **hilo de sesión**, un flujo de eventos con contexto aislado y su propio historial de conversación. El agente que ejecuta la sesión informa su actividad en el **hilo principal**, que es el [flujo de eventos](https://platform.claude.com/docs/es/managed-agents/events-and-streaming) a nivel de sesión. Se generan hilos adicionales en tiempo de ejecución cuando delega trabajo. Una ejecución de flujo de trabajo también crea hilos.
El hilo de un subagente es persistente. El agente puede enviar un seguimiento a un subagente al que llamó antes, y ese subagente conserva todo lo de sus turnos anteriores.
La configuración que usa un subagente depende de si es un [agente predefinido o inline](https://platform.claude.com/docs/es/managed-agents/multiagent-orchestration#predefined-and-inline-agents). Las [anulaciones de configuración del agente](https://platform.claude.com/docs/es/managed-agents/sessions#override-agent-configuration-for-a-session) a nivel de sesión se aplican al agente que ejecuta la sesión y a sus copias `self`. Cada agente conserva su propio historial de conversación.
### Enumerar los subagentes
Al [definir tu agente](https://platform.claude.com/docs/es/managed-agents/agent-setup), establece la lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`) en el bloque `multiagent` (csharp, go: `Multiagent`) para enumerar los agentes a los que puede delegar:
```bash cURL
curl -fsS https://api.anthropic.com/v1/agents \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d '{
"name": "Engineering Lead",
"model": "claude-opus-5-5",
"system": "You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.",
"tools": [
{
"type": "agent_toolset_20260401"
}
],
"multiagent": {
"type": "multiagent_20261001",
"subagents": {
"type": "enabled",
"predefined_agents": [
{"type": "agent", "id": "'"$REVIEWER_AGENT_ID"'"},
{"type": "agent", "id": "'"$TEST_WRITER_AGENT_ID"'"}
]
}
}
}'
```
```bash CLI
ant apply engineering-lead.md reviewer.md test-writer.md
```
```markdown
---
name: Engineering Lead
model: claude-opus-5-5
tools:
- type: agent_toolset_20260401
multiagent:
type: multiagent_20261001
subagents:
type: enabled
predefined_agents: # ant apply replaces each path with {type: agent, id, version}
- ./reviewer.md
- ./test-writer.md
---
You coordinate engineering work. Delegate code review to the reviewer agent
and test writing to the test agent.
```
```markdown
---
name: reviewer
model: claude-haiku-5-5
---
You are a code reviewer.
```
```markdown
---
name: test-writer
model: claude-haiku-5-5
---
You write unit tests.
```
```python Python
lead_agent = client.beta.agents.create(
name="Engineering Lead",
model="claude-opus-5-5",
system="You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.",
tools=[
{"type": "agent_toolset_20260401"},
],
multiagent={
"type": "multiagent_20261001",
"subagents": {
"type": "enabled",
"predefined_agents": [
{"type": "agent", "id": reviewer_agent.id},
{"type": "agent", "id": test_writer_agent.id},
],
},
},
)
```
```typescript TypeScript
const leadAgent = await client.beta.agents.create({
name: "Engineering Lead",
model: "claude-opus-5-5",
system:
"You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.",
tools: [{ type: "agent_toolset_20260401" }],
multiagent: {
type: "multiagent_20261001",
subagents: {
type: "enabled",
predefined_agents: [
{ type: "agent", id: reviewerAgent.id },
{ type: "agent", id: testWriterAgent.id }
]
}
}
});
```
```csharp C#
var leadAgent = await client.Beta.Agents.Create(new()
{
Name = "Engineering Lead",
Model = BetaManagedAgentsModel.ClaudeOpus5_5,
System = "You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.",
Tools =
[
new BetaManagedAgentsAgentToolset20260401Params
{
Type = BetaManagedAgentsAgentToolset20260401ParamsType.AgentToolset20260401,
},
],
Multiagent = new BetaManagedAgentsMultiagent20261001Params
{
Subagents = new BetaManagedAgentsMultiagentSubagentsEnabledParams
{
PredefinedAgents = [reviewerAgent.ID, testWriterAgent.ID],
},
},
});
```
```go Go
leadAgent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
Name: "Engineering Lead",
Model: anthropic.BetaManagedAgentsModelConfigParams{ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5},
System: anthropic.String("You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent."),
Tools: []anthropic.BetaAgentNewParamsToolUnion{{
OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
},
}},
Multiagent: anthropic.BetaManagedAgentsMultiagentParamsUnion{
OfMultiagent20261001: &anthropic.BetaManagedAgentsMultiagent20261001Params{
Subagents: anthropic.BetaManagedAgentsMultiagentSubagentsParamsUnion{
OfEnabled: &anthropic.BetaManagedAgentsMultiagentSubagentsEnabledParams{
PredefinedAgents: []anthropic.BetaManagedAgentsMultiagentPredefinedAgentParamsUnion{
{OfString: anthropic.String(reviewerAgent.ID)},
{OfString: anthropic.String(testWriterAgent.ID)},
},
},
},
},
},
})
if err != nil {
panic(err)
}
```
```java Java
var leadAgent = client.beta().agents().create(
AgentCreateParams.builder()
.name("Engineering Lead")
.model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5)
.system("You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.")
.addTool(
BetaManagedAgentsAgentToolset20260401Params.builder()
.type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
.build()
)
.multiagent(BetaManagedAgentsMultiagent20261001Params.builder()
.subagents(BetaManagedAgentsMultiagentSubagentsEnabledParams.builder()
.addPredefinedAgent(BetaManagedAgentsAgentParams.builder()
.type(BetaManagedAgentsAgentParams.Type.AGENT)
.id(reviewerAgent.id())
.build())
.addPredefinedAgent(BetaManagedAgentsAgentParams.builder()
.type(BetaManagedAgentsAgentParams.Type.AGENT)
.id(testWriterAgent.id())
.build())
.build())
.build())
.build()
);
```
```php PHP
$leadAgent = $client->beta->agents->create(
name: 'Engineering Lead',
model: 'claude-opus-5-5',
system: 'You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.',
tools: [
['type' => 'agent_toolset_20260401'],
],
multiagent: [
'type' => 'multiagent_20261001',
'subagents' => [
'type' => 'enabled',
'predefined_agents' => [
['type' => 'agent', 'id' => $reviewerAgent->id],
['type' => 'agent', 'id' => $testWriterAgent->id],
],
],
],
);
```
```ruby Ruby
lead_agent = client.beta.agents.create(
name: "Engineering Lead",
model: "claude-opus-5-5",
system: "You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.",
tools: [
{type: "agent_toolset_20260401"}
],
multiagent: {
type: "multiagent_20261001",
subagents: {
type: "enabled",
predefined_agents: [
{type: "agent", id: reviewer_agent.id},
{type: "agent", id: test_writer_agent.id}
]
}
}
)
```
El agente también puede delegar a agentes inline a menos que los desactives. Para esa configuración, y para las formas que adopta una entrada de la lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`), consulta [Agentes predefinidos e inline](https://platform.claude.com/docs/es/managed-agents/multiagent-orchestration#predefined-and-inline-agents).
`"advisor": {"type": "enabled", "model": ""}` le da al hilo principal de la sesión un asesor que puede consultar a mitad de turno. El asesor es una configuración del bloque `multiagent` (csharp, go: `Multiagent`), no una entrada de esta lista. Consulta [Darle un asesor a la sesión](https://platform.claude.com/docs/es/managed-agents/multiagent-orchestration#give-the-session-an-advisor).
Los flujos de trabajo dinámicos también están habilitados de forma predeterminada con este tipo, por lo que este agente puede planificar trabajo de gran tamaño que ejecuta muchos agentes en segundo plano. Para desactivarlos, o para enumerar agentes que un flujo de trabajo puede usar, consulta [Activar los flujos de trabajo dinámicos](https://platform.claude.com/docs/es/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows).
Las siguientes reglas se aplican a los agentes que enumeras en la lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`), y también a los agentes que enumeras en la lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `workflows` (csharp, go: `Workflows`):
* **Fijación:** La configuración del agente, incluida la lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`), se captura como instantánea cuando el agente se crea o se actualiza. Los agentes referenciados permanecen fijados a las versiones resueltas en ese momento y no adoptan actualizaciones posteriores de sus definiciones. Una actualización que no envía la lista conserva las versiones que ya están fijadas. Para delegar a una versión más reciente de un agente referenciado, [actualiza el agente](https://platform.claude.com/docs/es/managed-agents/agent-setup#update-an-agent) para que la lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`) haga referencia a esa versión.
* **Un nivel:** El agente puede delegar solo a un nivel de agentes. Hacer referencia a otro agente que tenga `multiagent` (csharp, go: `Multiagent`) configurado hace que la solicitud de creación o actualización falle con un error de validación 400.
* **Hasta 20 agentes:** La lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`) puede enumerar hasta 20 agentes únicos. El límite es por lista: la lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `workflows` (csharp, go: `Workflows`) también puede enumerar hasta 20. El agente puede llamar a varias copias de cada subagente, dentro del [límite de hilos](https://platform.claude.com/docs/es/managed-agents/session-threads) de la sesión.
* **Geografía de inferencia:** El agente y cada agente que enumeras, en la lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`) o de `workflows` (csharp, go: `Workflows`), deben fijar la misma [geografía de inferencia](https://platform.claude.com/docs/es/manage-claude/data-residency) (`inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) en el `model` (csharp, go: `Model`) de la [definición del agente](https://platform.claude.com/docs/es/managed-agents/agent-setup)), o ninguno de ellos puede fijar una. Una discrepancia en cualquiera de las listas se rechaza con un error de validación 400. Esa verificación se ejecuta tanto cuando se guarda el agente como cuando una [anulación al crear la sesión](https://platform.claude.com/docs/es/managed-agents/sessions#override-agent-configuration-for-a-session) cambia cualquiera de las fijaciones.
### Crear la sesión
Crea una sesión que haga referencia al agente. El agente delega a los agentes que enumeras en la lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`) según sea necesario. También puede delegar a [agentes inline](https://platform.claude.com/docs/es/managed-agents/multiagent-orchestration#predefined-and-inline-agents) a menos que los desactives.
```bash cURL
curl -fsSL https://api.anthropic.com/v1/sessions \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d '{
"agent": "'"$LEAD_AGENT_ID"'",
"environment_id": "'"$ENVIRONMENT_ID"'"
}'
```
```bash CLI
ant beta:sessions create \
--agent "$LEAD_AGENT_ID" \
--environment-id "$ENVIRONMENT_ID"
```
```python Python
session = client.beta.sessions.create(
agent=lead_agent.id,
environment_id=environment.id,
)
```
```typescript TypeScript
const session = await client.beta.sessions.create({
agent: leadAgent.id,
environment_id: environment.id
});
```
```csharp C#
var session = await client.Beta.Sessions.Create(new()
{
Agent = leadAgent.ID,
EnvironmentID = environment.ID,
});
```
```go Go
session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
Agent: anthropic.BetaSessionNewParamsAgentUnion{
OfString: anthropic.String(leadAgent.ID),
},
EnvironmentID: environment.ID,
})
if err != nil {
panic(err)
}
```
```java Java
var session = client.beta().sessions().create(SessionCreateParams.builder()
.agent(leadAgent.id())
.environmentId(environment.id())
.build());
```
```php PHP
$session = $client->beta->sessions->create(
agent: $leadAgent->id,
environmentID: $environment->id,
);
```
```ruby Ruby
session = client.beta.sessions.create(
agent: lead_agent.id,
environment_id: environment.id
)
```
### Conectar agentes a servidores MCP
Los servidores MCP tienen alcance de agente: cada definición de agente declara sus propios servidores y herramientas. Un agente inline no tiene definición de agente, por lo que usa los servidores MCP y las herramientas del agente que ejecuta la sesión. Las credenciales de vault tienen alcance de sesión: los `vault_ids` (java: `vaultIds`; php: `vaultIDs`; csharp: `VaultIds`; go: `VaultIDs`) pasados al crear la sesión se aplican a todos los hilos. Dos implicaciones para tu integración:
* Para autenticar los servidores MCP, incluye una credencial de vault para cada servidor MCP que use cualquiera de tus agentes.
* Para limitar el acceso de un agente, declara solo los servidores que necesita en su definición de agente. No puedes limitar un agente inline de esta manera. Para permitir solo los agentes que enumeras, deshabilita `inline_agents` (java, php: `inlineAgents`; csharp, go: `InlineAgents`) tanto en `subagents` (csharp, go: `Subagents`) como en `workflows` (csharp, go: `Workflows`), y enumera al menos un agente en cada uno. Consulta [Agentes predefinidos e inline](https://platform.claude.com/docs/es/managed-agents/multiagent-orchestration#predefined-and-inline-agents).
Las [anulaciones de configuración del agente](https://platform.claude.com/docs/es/managed-agents/sessions#override-agent-configuration-for-a-session) al crear la sesión pueden reemplazar los servidores MCP del agente que ejecuta la sesión y los de sus copias `self`.
Con un [entorno](https://platform.claude.com/docs/es/managed-agents/environments#networking) `limited`, la creación de la sesión falla con un error 400 cuando el agente, o un agente que enumeras en la lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`) o `workflows` (csharp, go: `Workflows`), declara un servidor MCP cuyo host no está en `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`). Establecer `allow_mcp_servers` (java: `allowMcpServers`; php: `allowMCPServers`; csharp: `AllowMcpServers`; go: `AllowMCPServers`) en `true` en la configuración de red del entorno desactiva esta verificación.
Crea el investigador, que declara el servidor MCP de GitHub, y el agente que delega al investigador:
```bash cURL
# Create the researcher
curl --fail-with-body -sS https://api.anthropic.com/v1/agents \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d '{
"name": "researcher",
"model": "claude-haiku-5-5",
"mcp_servers": [{"type": "url", "name": "github", "url": "https://api.githubcopilot.com/mcp/"}],
"tools": [{"type": "mcp_toolset", "mcp_server_name": "github"}]
}'
# Create the agent that delegates to it: research_agent_id is the id from the first response
curl --fail-with-body -sS https://api.anthropic.com/v1/agents \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d '{
"name": "lead",
"model": "claude-opus-5-5",
"tools": [{"type": "agent_toolset_20260401"}],
"multiagent": {
"type": "multiagent_20261001",
"subagents": {
"type": "enabled",
"predefined_agents": [{"type": "agent", "id": "'"$research_agent_id"'"}]
}
}
}'
```
```bash CLI
ant apply lead.md researcher.md
```
```markdown
---
name: lead
model: claude-opus-5-5
tools:
- type: agent_toolset_20260401
multiagent:
type: multiagent_20261001
subagents:
type: enabled
predefined_agents: # ant apply replaces each path with {type: agent, id, version}
- ./researcher.md
---
```
```markdown
---
name: researcher
model: claude-haiku-5-5
mcp_servers:
- type: url
name: github
url: https://api.githubcopilot.com/mcp/
tools:
- type: mcp_toolset
mcp_server_name: github
---
```
```python Python
research_agent = client.beta.agents.create(
name="researcher",
model="claude-haiku-5-5",
mcp_servers=[
{"type": "url", "name": "github", "url": "https://api.githubcopilot.com/mcp/"},
],
tools=[{"type": "mcp_toolset", "mcp_server_name": "github"}],
)
lead_agent = client.beta.agents.create(
name="lead",
model="claude-opus-5-5",
tools=[{"type": "agent_toolset_20260401"}],
multiagent={
"type": "multiagent_20261001",
"subagents": {
"type": "enabled",
"predefined_agents": [{"type": "agent", "id": research_agent.id}],
},
},
)
```
```typescript TypeScript
const researchAgent = await client.beta.agents.create({
name: "researcher",
model: "claude-haiku-5-5",
mcp_servers: [{ type: "url", name: "github", url: "https://api.githubcopilot.com/mcp/" }],
tools: [{ type: "mcp_toolset", mcp_server_name: "github" }]
});
const leadAgent = await client.beta.agents.create({
name: "lead",
model: "claude-opus-5-5",
tools: [{ type: "agent_toolset_20260401" }],
multiagent: {
type: "multiagent_20261001",
subagents: {
type: "enabled",
predefined_agents: [{ type: "agent", id: researchAgent.id }]
}
}
});
```
```csharp C#
var researchAgent = await client.Beta.Agents.Create(new()
{
Name = "researcher",
Model = BetaManagedAgentsModel.ClaudeHaiku5_5,
McpServers =
[
new()
{
Type = BetaManagedAgentsUrlMcpServerParamsType.Url,
Name = "github",
Url = "https://api.githubcopilot.com/mcp/",
},
],
Tools =
[
new BetaManagedAgentsMcpToolsetParams
{
Type = BetaManagedAgentsMcpToolsetParamsType.McpToolset,
McpServerName = "github",
},
],
});
var leadAgent = await client.Beta.Agents.Create(new()
{
Name = "lead",
Model = BetaManagedAgentsModel.ClaudeOpus5_5,
Tools =
[
new BetaManagedAgentsAgentToolset20260401Params
{
Type = BetaManagedAgentsAgentToolset20260401ParamsType.AgentToolset20260401,
},
],
Multiagent = new BetaManagedAgentsMultiagent20261001Params
{
Subagents = new BetaManagedAgentsMultiagentSubagentsEnabledParams
{
PredefinedAgents =
[
new BetaManagedAgentsAgentParams
{
Type = BetaManagedAgentsAgentParamsType.Agent,
ID = researchAgent.ID,
},
],
},
},
});
```
```go Go
researcher, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
Name: "researcher",
Model: anthropic.BetaManagedAgentsModelConfigParams{ID: anthropic.BetaManagedAgentsModelClaudeHaiku5_5},
MCPServers: []anthropic.BetaManagedAgentsURLMCPServerParams{{
Type: anthropic.BetaManagedAgentsURLMCPServerParamsTypeURL,
Name: "github",
URL: "https://api.githubcopilot.com/mcp/",
}},
Tools: []anthropic.BetaAgentNewParamsToolUnion{{
OfMCPToolset: &anthropic.BetaManagedAgentsMCPToolsetParams{
Type: anthropic.BetaManagedAgentsMCPToolsetParamsTypeMCPToolset,
MCPServerName: "github",
},
}},
})
if err != nil {
panic(err)
}
leadAgent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
Name: "lead",
Model: anthropic.BetaManagedAgentsModelConfigParams{ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5},
Tools: []anthropic.BetaAgentNewParamsToolUnion{{
OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
},
}},
Multiagent: anthropic.BetaManagedAgentsMultiagentParamsUnion{
OfMultiagent20261001: &anthropic.BetaManagedAgentsMultiagent20261001Params{
Subagents: anthropic.BetaManagedAgentsMultiagentSubagentsParamsUnion{
OfEnabled: &anthropic.BetaManagedAgentsMultiagentSubagentsEnabledParams{
PredefinedAgents: []anthropic.BetaManagedAgentsMultiagentPredefinedAgentParamsUnion{{
OfBetaManagedAgentsAgents: &anthropic.BetaManagedAgentsAgentParams{
Type: anthropic.BetaManagedAgentsAgentParamsTypeAgent,
ID: researcher.ID,
},
}},
},
},
},
},
})
if err != nil {
panic(err)
}
```
```java Java
var researcher = client.beta().agents().create(
AgentCreateParams.builder()
.name("researcher")
.model(BetaManagedAgentsModel.CLAUDE_HAIKU_5_5)
.addMcpServer(BetaManagedAgentsUrlMcpServerParams.builder()
.name("github")
.type(BetaManagedAgentsUrlMcpServerParams.Type.URL)
.url("https://api.githubcopilot.com/mcp/")
.build())
.addTool(BetaManagedAgentsMcpToolsetParams.builder()
.type(BetaManagedAgentsMcpToolsetParams.Type.MCP_TOOLSET)
.mcpServerName("github")
.build())
.build()
);
var leadAgent = client.beta().agents().create(
AgentCreateParams.builder()
.name("lead")
.model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5)
.addTool(BetaManagedAgentsAgentToolset20260401Params.builder()
.type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
.build())
.multiagent(BetaManagedAgentsMultiagent20261001Params.builder()
.subagents(BetaManagedAgentsMultiagentSubagentsEnabledParams.builder()
.addPredefinedAgent(BetaManagedAgentsAgentParams.builder()
.type(BetaManagedAgentsAgentParams.Type.AGENT)
.id(researcher.id())
.build())
.build())
.build())
.build()
);
```
```php PHP
$researchAgent = $client->beta->agents->create(
name: 'researcher',
model: 'claude-haiku-5-5',
mcpServers: [
['type' => 'url', 'name' => 'github', 'url' => 'https://api.githubcopilot.com/mcp/'],
],
tools: [
['type' => 'mcp_toolset', 'mcp_server_name' => 'github'],
],
);
$leadAgent = $client->beta->agents->create(
name: 'lead',
model: 'claude-opus-5-5',
tools: [
['type' => 'agent_toolset_20260401'],
],
multiagent: [
'type' => 'multiagent_20261001',
'subagents' => [
'type' => 'enabled',
'predefined_agents' => [
['type' => 'agent', 'id' => $researchAgent->id],
],
],
],
);
```
```ruby Ruby
research_agent = client.beta.agents.create(
name: "researcher",
model: "claude-haiku-5-5",
mcp_servers: [
{type: "url", name: "github", url: "https://api.githubcopilot.com/mcp/"}
],
tools: [
{type: "mcp_toolset", mcp_server_name: "github"}
]
)
lead_agent = client.beta.agents.create(
name: "lead",
model: "claude-opus-5-5",
tools: [
{type: "agent_toolset_20260401"}
],
multiagent: {
type: "multiagent_20261001",
subagents: {
type: "enabled",
predefined_agents: [
{type: "agent", id: research_agent.id}
]
}
}
)
```
Luego crea la sesión con el vault que contiene la credencial de GitHub:
```bash cURL
curl --fail-with-body -sS https://api.anthropic.com/v1/sessions \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d '{
"agent": "'"$lead_agent_id"'",
"environment_id": "'"$environment_id"'",
"vault_ids": ["'"$vault_id"'"]
}'
```
```bash CLI
ant beta:sessions create \
--agent "$lead_agent_id" \
--environment-id "$environment_id" \
--vault-id "$vault_id"
```
```python Python
session = client.beta.sessions.create(
agent=lead_agent.id,
environment_id=environment.id,
vault_ids=[vault.id],
)
print(session.id)
```
```typescript TypeScript
const session = await client.beta.sessions.create({
agent: leadAgent.id,
environment_id: environment.id,
vault_ids: [vault.id]
});
console.log(session.id);
```
```csharp C#
var session = await client.Beta.Sessions.Create(new()
{
Agent = leadAgent.ID,
EnvironmentID = environment.ID,
VaultIds = [vault.ID],
});
Console.WriteLine(session.ID);
```
```go Go
session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
Agent: anthropic.BetaSessionNewParamsAgentUnion{
OfString: anthropic.String(leadAgent.ID),
},
EnvironmentID: environment.ID,
VaultIDs: []string{vault.ID},
})
if err != nil {
panic(err)
}
fmt.Println(session.ID)
```
```java Java
var session = client.beta().sessions().create(SessionCreateParams.builder()
.agent(leadAgent.id())
.environmentId(environment.id())
.vaultIds(List.of(vault.id()))
.build());
IO.println(session.id());
```
```php PHP
$session = $client->beta->sessions->create(
agent: $leadAgent->id,
environmentID: $environment->id,
vaultIDs: [$vault->id],
);
echo "{$session->id}\n";
```
```ruby Ruby
session = client.beta.sessions.create(
agent: lead_agent.id,
environment_id: environment.id,
vault_ids: [vault.id]
)
puts session.id
```
En este ejemplo, solo el investigador declara el servidor MCP de GitHub, por lo que el agente que ejecuta la sesión no tiene acceso. Los `vault_ids` (java: `vaultIds`; php: `vaultIDs`; csharp: `VaultIds`; go: `VaultIDs`) de la sesión proporcionan la credencial de GitHub al hilo del investigador.
Si las llamadas MCP de un agente no logran autenticarse después de declarar el servidor, confirma que el `mcp_server_url` (java: `mcpServerUrl`; php: `mcpServerURL`; csharp: `McpServerUrl`; go: `MCPServerURL`) de la credencial se refiere al mismo servidor que el `mcp_servers[].url` (java, php: `mcpServers[].url`; csharp: `McpServers[].Url`; go: `MCPServers[].URL`) del agente. Ambas URL se normalizan antes de compararse (esquema y host en minúsculas, puertos predeterminados y barras finales eliminados), por lo que las diferencias en mayúsculas del host, un puerto predeterminado o una barra final no impiden una coincidencia; una ruta, un subdominio o un puerto no predeterminado diferentes sí lo hacen.
### Hilos
El hilo de sesión de cada agente tiene su propio flujo de eventos. Para listar, interrumpir o archivar hilos, leer sus eventos y gestionar los permisos de herramientas entre ellos, consulta [Hilos de sesión](https://platform.claude.com/docs/es/managed-agents/session-threads).
## Flujos de trabajo dinámicos
Con los flujos de trabajo dinámicos, un agente puede asumir trabajo con muchas partes, como revisar cientos de documentos o verificar de forma cruzada muchas fuentes. El agente escribe un **workflow** (flujo de trabajo): un programa que ejecuta muchos agentes en fases y combina lo que devuelven. El servidor lo ejecuta en segundo plano como una **workflow run** (ejecución de flujo de trabajo), mientras el agente sigue trabajando o termina su turno. Activas o desactivas los flujos de trabajo dinámicos con la configuración `workflows` (csharp, go: `Workflows`) en el bloque `multiagent` (csharp, go: `Multiagent`) del agente. Los agentes de una ejecución pueden trabajar al mismo tiempo, por lo que una tarea larga puede terminar antes que si un solo agente hiciera cada parte una tras otra.
* **Cómo comienza una ejecución:** Describes el trabajo en un `user.message`. A partir de eso, el agente determina si iniciar una ejecución y cuándo, por lo que no hay ninguna llamada adicional a la API. En cambio, influyes en la determinación del agente describiendo cuándo usar una ejecución en `user.message` o en la indicación del sistema del agente. (Las políticas de permisos se aplican a las herramientas que llaman los agentes de una ejecución, no al inicio de la ejecución).
* **Qué agentes usa:** [Agentes inline](https://platform.claude.com/docs/es/managed-agents/multiagent-orchestration#predefined-and-inline-agents) que define el flujo de trabajo, agentes predefinidos que enumeras en la lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `workflows` (csharp, go: `Workflows`), o ambos. Si no enumeras ninguno, el flujo de trabajo los define todos. Un agente inline usa el modelo del agente que ejecuta la sesión. Para permitir que una ejecución use otro modelo para algunos de sus agentes, créalos como agentes y enuméralos en la lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `workflows` (csharp, go: `Workflows`).
* **Cómo la sigues:** Los eventos de la ejecución llegan al flujo de eventos de la sesión, y cada agente de la ejecución trabaja en un [hilo de sesión](https://platform.claude.com/docs/es/managed-agents/session-threads) que puedes listar, leer y transmitir por streaming. Consulta [Ejecuciones de flujos de trabajo](https://platform.claude.com/docs/es/managed-agents/workflow-runs) para conocer los eventos, las interrupciones, los [límites](https://platform.claude.com/docs/es/managed-agents/workflow-runs#limits) y [lo que muestran los hilos de una ejecución](https://platform.claude.com/docs/es/managed-agents/workflow-runs#a-runs-threads).
### Activar los flujos de trabajo dinámicos
Al [definir tu agente](https://platform.claude.com/docs/es/managed-agents/agent-setup), establece `multiagent.type` en `"multiagent_20261001"` y habilita `workflows`. Los flujos de trabajo dinámicos y la delegación (`subagents`) están activados de forma predeterminada con este tipo. Para usar solo flujos de trabajo dinámicos, agrega `"subagents": {"type": "disabled"}`.
Antes de cambiar el `multiagent.type` de un agente existente, consulta [cómo mover un agente a este tipo](https://platform.claude.com/docs/es/managed-agents/multiagent-orchestration#move-from-the-coordinator-type).
```bash cURL
curl -fsS https://api.anthropic.com/v1/agents \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d '{
"name": "Contract Reviewer",
"model": "claude-opus-5-5",
"system": "You review contracts. When you are asked to review more than a few contracts, start a workflow run that reads them in parallel and combines the findings. Review one or two contracts yourself, without a run.",
"tools": [{"type": "agent_toolset_20260401"}],
"multiagent": {"type": "multiagent_20261001", "workflows": {"type": "enabled"}}
}'
```
```bash CLI
ant apply contract-reviewer.md
```
```markdown
---
name: Contract Reviewer
model: claude-opus-5-5
tools:
- type: agent_toolset_20260401
multiagent:
type: multiagent_20261001
workflows:
type: enabled
---
You review contracts. When you're asked to review more than a few contracts, start a workflow run that reads them in parallel and combines the findings. Review one or two contracts yourself, without a run.
```
```python Python
agent = client.beta.agents.create(
name="Contract Reviewer",
model="claude-opus-5-5",
system="You review contracts. When you're asked to review more than a few contracts, start a workflow run that reads them in parallel and combines the findings. Review one or two contracts yourself, without a run.",
tools=[{"type": "agent_toolset_20260401"}],
multiagent={"type": "multiagent_20261001", "workflows": {"type": "enabled"}},
)
```
```typescript TypeScript
const agent = await client.beta.agents.create({
name: "Contract Reviewer",
model: "claude-opus-5-5",
system:
"You review contracts. When you're asked to review more than a few contracts, start a workflow run that reads them in parallel and combines the findings. Review one or two contracts yourself, without a run.",
tools: [{ type: "agent_toolset_20260401" }],
multiagent: { type: "multiagent_20261001", workflows: { type: "enabled" } }
});
```
```csharp C#
var agent = await client.Beta.Agents.Create(new()
{
Name = "Contract Reviewer",
Model = BetaManagedAgentsModel.ClaudeOpus5_5,
System = "You review contracts. When you're asked to review more than a few contracts, start a workflow run that reads them in parallel and combines the findings. Review one or two contracts yourself, without a run.",
Tools =
[
new BetaManagedAgentsAgentToolset20260401Params
{
Type = BetaManagedAgentsAgentToolset20260401ParamsType.AgentToolset20260401,
},
],
// La clase de configuración establece el tipo por ti.
Multiagent = new BetaManagedAgentsMultiagent20261001Params
{
Workflows = new BetaManagedAgentsMultiagentWorkflowsEnabledParams(),
},
});
```
```go Go
agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
Name: "Contract Reviewer",
Model: anthropic.BetaManagedAgentsModelConfigParams{ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5},
System: anthropic.String("You review contracts. When you're asked to review more than a few contracts, start a workflow run that reads them in parallel and combines the findings. Review one or two contracts yourself, without a run."),
Tools: []anthropic.BetaAgentNewParamsToolUnion{{
OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
},
}},
Multiagent: anthropic.BetaManagedAgentsMultiagentParamsUnion{
OfMultiagent20261001: &anthropic.BetaManagedAgentsMultiagent20261001Params{
Workflows: anthropic.BetaManagedAgentsMultiagentWorkflowsParamsUnion{
OfEnabled: &anthropic.BetaManagedAgentsMultiagentWorkflowsEnabledParams{},
},
},
},
})
if err != nil {
panic(err)
}
```
```java Java
var agent = client.beta().agents().create(
AgentCreateParams.builder()
.name("Contract Reviewer")
.model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5)
.system("You review contracts. When you're asked to review more than a few contracts, start a workflow run that reads them in parallel and combines the findings. Review one or two contracts yourself, without a run.")
.addTool(
BetaManagedAgentsAgentToolset20260401Params.builder()
.type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
.build()
)
// La clase de configuración establece el tipo por ti.
.multiagent(BetaManagedAgentsMultiagent20261001Params.builder()
.workflows(BetaManagedAgentsMultiagentWorkflowsEnabledParams.builder().build())
.build())
.build()
);
```
```php PHP
$agent = $client->beta->agents->create(
name: 'Contract Reviewer',
model: 'claude-opus-5-5',
system: "You review contracts. When you're asked to review more than a few contracts, start a workflow run that reads them in parallel and combines the findings. Review one or two contracts yourself, without a run.",
tools: [
['type' => 'agent_toolset_20260401'],
],
multiagent: ['type' => 'multiagent_20261001', 'workflows' => ['type' => 'enabled']],
);
```
```ruby Ruby
agent = client.beta.agents.create(
name: "Contract Reviewer",
model: "claude-opus-5-5",
system_: "You review contracts. When you're asked to review more than a few contracts, start a workflow run that reads them in parallel and combines the findings. Review one or two contracts yourself, without a run.",
tools: [
{type: "agent_toolset_20260401"}
],
multiagent: {type: "multiagent_20261001", workflows: {type: "enabled"}}
)
```
Para permitir que un flujo de trabajo use agentes que ya creaste, enuméralos en `workflows.predefined_agents`. Las configuraciones `subagents` y `advisor` van en el mismo bloque `multiagent`. Para enumerar subagentes, consulta [Delegar a subagentes](https://platform.claude.com/docs/es/managed-agents/multiagent-orchestration#delegate-to-subagents). Para configurar un asesor, consulta [Darle un asesor a la sesión](https://platform.claude.com/docs/es/managed-agents/multiagent-orchestration#give-the-session-an-advisor). Este agente permite que un flujo de trabajo use un agente que creaste, enumera dos subagentes y tiene un asesor:
```json
{
"multiagent": {
"type": "multiagent_20261001",
"workflows": {
"type": "enabled",
"predefined_agents": [{ "type": "agent", "id": "agent_01Lm4cV8yQ2tNs7XbKdR5h" }]
},
"subagents": {
"type": "enabled",
"predefined_agents": [
{ "type": "agent", "id": "agent_01J8XkN5uT3vHpLqRfWdY2" },
{ "type": "agent", "id": "agent_01HqR2k7vXbZ9mNpL3wYcT" }
]
},
"advisor": { "type": "enabled", "model": "claude-opus-5-5" }
}
}
```
Cada configuración se habilita o deshabilita por separado:
| Configuración | Qué activa | Los agentes van en | Valor predeterminado |
| ------------- | ------------------------------------------------------------------------------------------- | --------------------------------------- | -------------------- |
| `workflows` | Flujos de trabajo dinámicos | `workflows.predefined_agents`, hasta 20 | Habilitado |
| `subagents` | Delegación a subagentes: los agentes que enumeras y los agentes que el propio agente define | `subagents.predefined_agents`, hasta 20 | Habilitado |
| `advisor` | Un modelo asesor | Ninguno. Establece `model`. | Deshabilitado |
Para saber qué va en cada lista y cómo permitir solo los agentes que enumeras, consulta [Agentes predefinidos e inline](https://platform.claude.com/docs/es/managed-agents/multiagent-orchestration#predefined-and-inline-agents).
Ten en cuenta lo siguiente:
* **Actualización:** Una actualización que mantiene el tipo `multiagent_20261001` cambia solo lo que envía:
* Una configuración o un campo que omites conserva su valor almacenado.
* Una configuración o un campo que envías como `null` toma su valor predeterminado, al igual que todo lo que contiene, sin importar lo que tuvieras almacenado.
* Una lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) que envías reemplaza la lista almacenada.
* Una configuración que envías con un `type` diferente reemplaza la configuración almacenada, y los campos que omites en ella toman sus valores predeterminados.
* Cada objeto que envías necesita su `type`, y un `advisor` habilitado necesita su `model`.
* **Desactivación:** Establece `workflows` en `{"type": "disabled"}`. Permanece desactivado hasta que una actualización lo vuelva a activar. Enviar `null` lo activa, porque su valor predeterminado es habilitado. Lo mismo aplica a `subagents`.
* **Sesiones existentes:** Una sesión copia la configuración cuando se crea, por lo que cambiar el agente después no cambia una sesión que ya existe.
* **Agentes que puedes enumerar:** Un agente que tiene `multiagent` (csharp, go: `Multiagent`) configurado no puede enumerarse como subagente de otro agente, ni en la lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `workflows` (csharp, go: `Workflows`) en otro agente. Un agente puede enumerarse a sí mismo en cualquiera de las dos listas con `{"type": "self"}`, que se devuelve como su propio `id` y `version`.
* **Nombres de herramientas:** El prefijo `ant__` está reservado. Si tu agente ya tiene una herramienta personalizada cuyo nombre comienza con `ant__`, una actualización falla con un error 400 hasta que envíes `tools` (csharp, go: `Tools`) sin ese nombre. Una nueva sesión también se rechaza con un error 400 si su agente, o un agente en cualquiera de las listas, tiene una herramienta así. Cambia el nombre de la herramienta o elimínala en la misma actualización que activa los flujos de trabajo dinámicos. Consulta [Herramientas personalizadas](https://platform.claude.com/docs/es/managed-agents/tools#custom-tools).
* **Presupuesto:** Establece un [presupuesto de sesión](https://platform.claude.com/docs/es/managed-agents/budgets) al crear la sesión para limitar el gasto de la sesión, incluidas las ejecuciones; no puedes agregar uno a una sesión existente. Las ejecuciones se pausan cuando la sesión alcanza el presupuesto, y las ejecuciones que el presupuesto pausó se reanudan cuando lo aumentas o lo eliminas, a menos que una interrupción también las haya pausado. Consulta [Costo y presupuestos](https://platform.claude.com/docs/es/managed-agents/workflow-runs#cost-and-budgets).
### Indicarle al agente cuándo usar una ejecución
Activar los flujos de trabajo dinámicos le da al agente la capacidad de iniciar ejecuciones de flujos de trabajo. El agente determina cuándo iniciar una. Para orientar esa decisión, agrega una instrucción como la siguiente a la indicación del sistema del agente. El agente de revisión de contratos de [Activar los flujos de trabajo dinámicos](https://platform.claude.com/docs/es/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows) usa esta indicación del sistema:
```text wrap
You review contracts. When you're asked to review more than a few contracts, start a workflow run that reads them in parallel and combines the findings. Review one or two contracts yourself, without a run.
```
Para adaptarla, nombra las tareas del dominio de tu agente que requieren una ejecución y las tareas pequeñas que el agente debe hacer por sí mismo. También puedes orientar cómo una ejecución realiza el trabajo, como en estos ejemplos:
* **Cómo dividir el trabajo:** "En una ejecución, usa un agente por contrato. Luego haz que un segundo agente revise cada contrato, no solo aquellos en los que el primer agente encontró algo, y busque lo que el primer agente pasó por alto. Todo lo que no pase la revisión se rehace y se revisa de nuevo."
* **Qué hacer cuando un agente falla:** "Que un agente falle no debe hacer fallar la ejecución. Si un agente no logra leer un contrato, marca ese contrato como no cubierto. Cuando termine la ejecución, dime qué contratos no se cubrieron."
* **Un límite de tiempo:** "Dale a la ejecución un límite de tiempo de una hora."
* **Planifica primero:** "Antes de iniciar una ejecución, describe sus fases y cuántos agentes ejecuta cada una. Luego espera mi aprobación." No hay un paso de aprobación antes de que comience una ejecución, así que nada hace cumplir esto.
Limita las ejecuciones a las tareas que las necesitan, porque cada agente en una ejecución usa tokens.
Luego [crea una sesión](https://platform.claude.com/docs/es/managed-agents/sessions) con el agente, como lo harías con cualquier agente, y describe el trabajo en un `user.message`. También puedes pedir una ejecución en ese mensaje.
Para conocer los eventos de una ejecución, cómo interrumpir una sesión con ejecuciones abiertas, qué cambia mientras una ejecución está abierta, y los presupuestos y límites, consulta [Ejecuciones de flujos de trabajo](https://platform.claude.com/docs/es/managed-agents/workflow-runs).
## Darle un asesor a la sesión
Una configuración `advisor` habilitada en el bloque `multiagent` (csharp, go: `Multiagent`) del agente le da al hilo principal de la sesión un **asesor**: un modelo que puede consultar a mitad de turno para obtener orientación estratégica, como planificar un enfoque, desatascarse o revisar el trabajo antes de terminar. La configuración está deshabilitada de forma predeterminada. Para habilitarla, establece `advisor` en `{"type": "enabled", "model": "..."}`, que tiene exactamente dos campos, `type` y `model`:
```bash cURL
curl -fsS https://api.anthropic.com/v1/agents \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d '{
"name": "Backend engineer",
"model": "claude-sonnet-5",
"system": "You implement backend features end to end. Consult the advisor before major backend design decisions.",
"multiagent": {
"type": "multiagent_20261001",
"advisor": {"type": "enabled", "model": "claude-opus-5-5"}
}
}'
```
```bash CLI
ant apply backend-engineer.md
```
```markdown
---
name: Backend engineer
model: claude-sonnet-5
multiagent:
type: multiagent_20261001
advisor:
type: enabled
model: claude-opus-5-5
---
You implement backend features end to end. Consult the advisor before major backend design decisions.
```
```python Python
agent = client.beta.agents.create(
name="Backend engineer",
model="claude-sonnet-5",
system="You implement backend features end to end. Consult the advisor before major backend design decisions.",
multiagent={
"type": "multiagent_20261001",
"advisor": {"type": "enabled", "model": "claude-opus-5-5"},
},
)
print(agent.id)
```
```typescript TypeScript
const agent = await client.beta.agents.create({
name: "Backend engineer",
model: "claude-sonnet-5",
system:
"You implement backend features end to end. Consult the advisor before major backend design decisions.",
multiagent: {
type: "multiagent_20261001",
advisor: { type: "enabled", model: "claude-opus-5-5" }
}
});
console.log(agent.id);
```
```csharp C#
var agent = await client.Beta.Agents.Create(new()
{
Name = "Backend engineer",
Model = BetaManagedAgentsModel.ClaudeSonnet5,
System = "You implement backend features end to end. Consult the advisor before major backend design decisions.",
Multiagent = new BetaManagedAgentsMultiagent20261001Params
{
Advisor = new BetaManagedAgentsMultiagentAdvisorEnabledParams { Model = "claude-opus-5-5" },
},
});
Console.WriteLine(agent.ID);
```
```go Go
agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
Name: "Backend engineer",
Model: anthropic.BetaManagedAgentsModelConfigParams{ID: anthropic.BetaManagedAgentsModelClaudeSonnet5},
System: anthropic.String("You implement backend features end to end. Consult the advisor before major backend design decisions."),
Multiagent: anthropic.BetaManagedAgentsMultiagentParamsUnion{
OfMultiagent20261001: &anthropic.BetaManagedAgentsMultiagent20261001Params{
Advisor: anthropic.BetaManagedAgentsMultiagentAdvisorParamsUnion{
OfEnabled: &anthropic.BetaManagedAgentsMultiagentAdvisorEnabledParams{
Model: "claude-opus-5-5",
},
},
},
},
})
if err != nil {
panic(err)
}
fmt.Println(agent.ID)
```
```java Java
var agent = client.beta().agents().create(
AgentCreateParams.builder()
.name("Backend engineer")
.model(BetaManagedAgentsModel.CLAUDE_SONNET_5)
.system("You implement backend features end to end. Consult the advisor before major backend design decisions.")
.multiagent(BetaManagedAgentsMultiagent20261001Params.builder()
.advisor(BetaManagedAgentsMultiagentAdvisorEnabledParams.builder()
.model("claude-opus-5-5")
.build())
.build())
.build()
);
IO.println(agent.id());
```
```php PHP
$agent = $client->beta->agents->create(
name: 'Backend engineer',
model: 'claude-sonnet-5',
system: 'You implement backend features end to end. Consult the advisor before major backend design decisions.',
multiagent: [
'type' => 'multiagent_20261001',
'advisor' => ['type' => 'enabled', 'model' => 'claude-opus-5-5'],
],
);
echo $agent->id, PHP_EOL;
```
```ruby Ruby
agent = client.beta.agents.create(
name: "Backend engineer",
model: "claude-sonnet-5",
system_: "You implement backend features end to end. Consult the advisor before major backend design decisions.",
multiagent: {
type: "multiagent_20261001",
advisor: {type: "enabled", model: "claude-opus-5-5"}
}
)
puts agent.id
```
Este ejemplo establece solo `advisor` (csharp, go: `Advisor`). Las otras dos configuraciones, `subagents` (csharp, go: `Subagents`) y `workflows` (csharp, go: `Workflows`), conservan sus valores predeterminados, por lo que ambas están habilitadas, y el agente también puede delegar a agentes inline e iniciar ejecuciones de flujos de trabajo. Para un agente que consulta a un asesor y hace todo el trabajo por sí mismo, establece ambas en `{"type": "disabled"}`.
No puedes enumerar al asesor en la lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`) o `workflows` (csharp, go: `Workflows`). Un `advisor` (csharp, go: `Advisor`) habilitado reserva el nombre `anthropic.advisor`. Mientras esté habilitado, ninguna de las listas puede contener un agente llamado literalmente `anthropic.advisor`: la solicitud se rechaza con un error de validación 400.
El modelo asesor debe cumplir un nivel mínimo de capacidad, y el modelo propio del agente no debe ser más capaz que su asesor; los modelos de igual capacidad pueden emparejarse. Un emparejamiento no válido se rechaza con un error de validación 400 cuando se guarda el agente, y de nuevo cuando se crea una sesión. El emparejamiento también se verifica cuando comienza cada consulta: si ya no es válido, esa consulta falla y la sesión continúa. Los emparejamientos válidos siguen la tabla de [compatibilidad de modelos](https://platform.claude.com/docs/es/agents-and-tools/tool-use/advisor-tool#model-compatibility) de la herramienta de asesor.
El asesor también está disponible como una [herramienta de servidor en la Messages API](https://platform.claude.com/docs/es/agents-and-tools/tool-use/advisor-tool). La superficie de Managed Agents difiere en configuración y entrega: la configuración `advisor` (csharp, go: `Advisor`) no tiene campos `max_uses`, `max_tokens` ni `caching`, y los consejos llegan a través de eventos de hilo en lugar de bloques `advisor_tool_result`.
### Cómo funcionan las consultas
Cada consulta se ejecuta como un hilo generado por la plataforma llamado `anthropic.advisor` que se termina a sí mismo cuando la consulta se completa, y el consejo se entrega al hilo principal como un evento `agent.thread_message_received`. Una consulta emite los eventos de hilo estándar, identificados por el nombre reservado `anthropic.advisor` (los eventos del ciclo de vida del hilo lo llevan como `agent_name` (java, php: `agentName`; csharp, go: `AgentName`), y la entrega del consejo lo lleva como `from_agent_name` (java, php: `fromAgentName`; csharp, go: `FromAgentName`)), normalmente en este orden:
1. `session.thread_created`
2. `session.thread_status_running`
3. `agent.thread_message_received` (el consejo)
4. `session.thread_status_idle` (`stop_reason: end_turn`)
5. `session.thread_status_terminated`
No se emiten eventos `agent.tool_use` para una consulta, y no aparece ningún evento `agent.thread_message_sent` en el flujo de eventos de la sesión, porque la entrada de la consulta la compone la plataforma en lugar de enviarla el agente. Si listas los eventos del propio hilo del asesor, el consejo también aparece allí como un evento `agent.thread_message_sent`. No se garantiza que la entrega del consejo (evento 3) llegue antes de los eventos de inactividad y terminación del hilo del asesor, así que no los trates como una señal de que el consejo ya se entregó.
Si tu cliente puede leer el consejo depende de la política del modelo asesor. Refleja la división de [variantes de resultado](https://platform.claude.com/docs/es/agents-and-tools/tool-use/advisor-tool#result-variants) de la herramienta de asesor de la Messages API. Un modelo asesor que devuelve resultados en texto plano allí entrega texto legible aquí. Uno que devuelve resultados redactados entrega un marcador de posición `[{"type": "redacted"}]` en todas las superficies del cliente, mientras que el agente sigue leyendo el consejo completo del lado del servidor. El ejemplo anterior usa como asesor el modelo Opus más reciente disponible para ti. Claude Opus 5.5 devuelve resultados redactados, por lo que tu cliente solo ve el marcador de posición. Para leer el consejo en el flujo de eventos, usa un asesor que devuelva texto plano, como Claude Opus 4.8. La política de un modelo puede cambiar sin ningún cambio en la API, así que maneja tanto los bloques `text` como los `redacted`. Algunos modelos de agente solo se emparejan con asesores de resultados redactados; consulta la [tabla de compatibilidad](https://platform.claude.com/docs/es/agents-and-tools/tool-use/advisor-tool#model-compatibility) de la herramienta de asesor. El pensamiento del asesor nunca se expone. Los clientes no pueden enviar bloques `redacted` por sí mismos; un evento que contenga uno se rechaza con un error de validación 400.
Una consulta fallida o interrumpida nunca hace fallar el turno del agente: el agente continúa después de un aviso genérico de que la consulta falló. Un `user.interrupt` a nivel de sesión durante una consulta termina el hilo del asesor sin entregar ningún consejo; un `user.interrupt` con el `session_thread_id` (java: `sessionThreadId`; php: `sessionThreadID`; csharp, go: `SessionThreadID`) del hilo del asesor abandona solo esa consulta.
### Hilos del asesor
El asesor no es un subagente. La herramienta `list_agents` del agente no lo muestra, y `send_to_agent`, que envía a un subagente un mensaje de seguimiento, no puede alcanzarlo. Solo el hilo principal de la sesión puede consultarlo; los subagentes no pueden.
Los hilos del asesor están exentos del límite de 25 hilos hijos. Aparecen en la [lista de hilos](https://platform.claude.com/docs/es/managed-agents/session-threads) de la sesión. Su `agent` es la forma de asesor, `{"type": "advisor", "model": ...}`, con el modelo que configuraste, y su `parent_thread_id` es el hilo principal.
El almacenamiento en caché de prompts del lado del asesor es automático; no hay nada que configurar. Las consultas se facturan según las tarifas del modelo asesor, y sus tokens aparecen en el uso del hilo del asesor y en los totales de uso de la sesión. También cuentan para un [presupuesto de sesión](https://platform.claude.com/docs/es/managed-agents/budgets), al precio de lista del modelo asesor. Cada consulta envía al asesor la conversación del hilo principal hasta ese momento, por lo que las consultas tardías en una sesión larga usan más tokens de entrada.
### Eliminar el asesor
Para eliminar el asesor, [actualiza el agente](https://platform.claude.com/docs/es/managed-agents/agent-setup#update-an-agent) con `advisor` establecido en `{"type": "disabled"}`. En un agente que ya tiene el tipo `multiagent_20261001`, una configuración que la actualización omite conserva su valor almacenado, por lo que no necesitas enviar `subagents` ni `workflows` de nuevo. Por la misma razón, una actualización que omite `advisor` conserva el asesor. Antes de cambiar el `multiagent.type` de un agente existente, consulta [cómo mover un agente a este tipo](https://platform.claude.com/docs/es/managed-agents/multiagent-orchestration#move-from-the-coordinator-type).
## Migrar desde el tipo `coordinator`
Al igual que `multiagent_20261001`, el tipo `coordinator` permite que un agente delegue a subagentes que enumeras y consulte a un modelo asesor. Con el tipo `coordinator`, el agente no puede iniciar ejecuciones de flujos de trabajo ni definir subagentes por sí mismo. La API acepta ambos tipos.
Para mover un agente a `multiagent_20261001`, [actualiza el agente](https://platform.claude.com/docs/es/managed-agents/agent-setup#update-an-agent) con un bloque `multiagent` de ese tipo:
1. Establece `type` en `"multiagent_20261001"`.
2. Enumera los agentes que el agente puede llamar en `subagents.predefined_agents`. Las entradas conservan la forma que tienen ahora.
3. Si el agente tiene un asesor, establece `advisor` en `{"type": "enabled", "model": "..."}` con el modelo del asesor.
4. Envía el bloque completo en una sola actualización.
Por ejemplo, este bloque le da a un agente dos subagentes y un asesor:
```json
{
"multiagent": {
"type": "multiagent_20261001",
"subagents": {
"type": "enabled",
"predefined_agents": [
{ "type": "agent", "id": "agent_01J8XkN5uT3vHpLqRfWdY2" },
{ "type": "agent", "id": "agent_01HqR2k7vXbZ9mNpL3wYcT" }
]
},
"advisor": { "type": "enabled", "model": "claude-opus-5-5" }
}
}
```
Ese bloque omite `workflows` y `subagents.inline_agents`, por lo que ambos toman su valor predeterminado y están habilitados. El agente migrado también puede iniciar ejecuciones de flujos de trabajo y definir subagentes por sí mismo. Para mantener cualquiera de los dos desactivado, establécelo en `{"type": "disabled"}` en la misma actualización. Consulta [Activar los flujos de trabajo dinámicos](https://platform.claude.com/docs/es/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows) y [Agentes predefinidos e inline](https://platform.claude.com/docs/es/managed-agents/multiagent-orchestration#predefined-and-inline-agents).
Si el agente tiene un asesor y no tiene subagentes, establece `subagents` en `{"type": "disabled"}` para mantener la delegación desactivada. Una solicitud que deshabilita `subagents.inline_agents` y no enumera ningún agente falla con un error 400.
La actualización reemplaza el bloque `multiagent` completo, así que envía de nuevo la lista de agentes y el asesor, como hace el ejemplo. Lo que omites toma su valor predeterminado:
* **`subagents.predefined_agents`:** La lista queda vacía, por lo que el agente pierde los subagentes que enumeraste.
* **`advisor`:** El asesor se deshabilita.
Una vez que el agente tiene el tipo `multiagent_20261001`, una configuración que una actualización posterior omite conserva su valor almacenado.
La actualización no cambia las sesiones que ya existen. Para usar el nuevo bloque, crea una sesión después de la actualización.