Passo 2 · Modelo mental · Modelo mental · Schema & policy ENPT
Kimi CLI AgentSwarm · Curso Visual

Schema & policy exclusive-deny

O contrato que toda chamada de swarm deve satisfazer — e por que o modelo não pode misturar AgentSwarm com outras tools no mesmo turno.

Leia a versão simples ou abra a camada técnica em qualquer seção.
1

A ideia central

Cada chamada AgentSwarm é um fan-out estruturado. Você fornece um template com placeholder {{item}} e um array items — cada string vira o prompt concreto de um subagente. Perfil padrão: coder; use explore para varreduras paralelas read-only.

Regras de validação do binário (Zod AgentSwarmToolInputSchema):

  • Mínimo 2 items salvo se resume_agent_ids for fornecido
  • prompt_template deve conter {{item}} ao usar items
  • Prompts expandidos duplicados são rejeitados
  • Máximo 128 subagentes por chamada

resume_agent_ids é um mapa (agent_id → prompt de resume), não um array. Retoma subagentes existentes antes de lançar novos por items.

Depois vem a policy exclusive-deny: AgentSwarm deve ser a única tool call na resposta do modelo. Sem Read + AgentSwarm no mesmo turno. Explore primeiro, swarm sozinho depois.

Pense assim… um mail merge em massa. O template é a carta; cada item preenche a linha do destinatário. Você não faz mail merge e arquiva papelada no mesmo instante — o runtime força uma ação por vez para que o lançamento do swarm seja atômico e auditável.

Reconstrução do schema

type AgentSwarmInput = {
  description: string;
  subagent_type?: string;              // default "coder"
  prompt_template?: string;            // obrigatório com items
  items?: string[];                    // máx 128
  resume_agent_ids?: Record<string, string>;
};

Formato de saída

<agent_swarm_result>
  <summary>completed: 8</summary>
  <subagent agent_id="agent-0" item="claude" outcome="completed">...</subagent>
  <resume_hint>Call AgentSwarm with resume_agent_ids...</resume_hint>
</agent_swarm_result>

Outcomes por subagente: completed, failed, aborted (de renderSwarmSummary no binário).

2

Em uma imagem

prompt_template Review {{item}} for regressions items: ["src/a.ts","src/b.ts"] agent-0: Review src/a.ts… agent-1: Review src/b.ts… exclusive-deny Read + AgentSwarm → DENY 2× AgentSwarm → DENY AgentSwarm alone → OK
Topo: template + items expandem para prompts distintos. Direita: agent-swarm-exclusive-deny rejeita chamadas mistas ou duplicadas no mesmo turno.
3

No código

Chamada real da sessão 30e21381 — 8 subagentes paralelos, todos completaram.

wire.jsonl — AgentSwarm tool.call 
{
  "name": "AgentSwarm",
  "args": {
    "description": "Extract agent sessions & assets",
    "subagent_type": "coder",
    "items": ["claude", "grok", "kimi", "codex",
              "appfy-projects", "loop-engineering-suite",
              "agent-swarm", "gmail-auth"],
    "prompt_template": "Your specific scope is: {{item}}. ..."
  }
}
agent-swarm-exclusive-deny.ts (embutido no binário) 
evaluate(context) {
  const n = toolCalls.filter(t => t.name === "AgentSwarm").length;
  if (n === 0) return;
  if (n === 1 && toolCalls.length === 1) return; // OK
  return { kind: "deny", message: "AgentSwarm must be called one swarm at a time." };
}

Quando usar qual

Agent — um subagente, prompt completo único. AgentSwarm — N subagentes, mesmo template + items distintos. Subagentes não recebem AgentSwarm nem Agent na tool list.

4

Experimente: cenários exclusive-deny

Escolha um padrão de tool calls. Veja se agent-swarm-exclusive-deny permite ou bloqueia.

Próximo: rampa do SubagentBatch — como o runtime lança os subagentes e o que fica em wire.jsonl e state.json.