Phase 14 - Lesson 17

Claude Agent SDK: Subagentes e Session Store

O Claude Agent SDK é a versão em biblioteca do harness do Claude Code. Ferramentas integradas, subagentes para isolamento de contexto, hooks, propagação de traces W3C, paridade de Session Store. O Claude Managed Agents é a alternativa hospedada para tarefas assíncronas de longa duração.

Tipo: Aprender + Construir Idiomas: Python (stdlib) Pré-requisitos: Phase 14 · 01 (Agent Loop), Phase 14 · 10 (Skill Libraries) Tempo: ~75 minutos

Objetivos de Aprendizagem

• Explicar a diferença entre o Anthropic Client SDK (API bruta) e o Claude Agent SDK (formato de harness).
• Descrever subagentes — paralelização e isolamento de contexto — e quando utilizá-los.
• Nomear a interface de Session Store do SDK Python (append, load, list_sessions, delete, list_subkeys) e o papel do --session-mirror.
• Implementar um harness com stdlib contendo ferramentas integradas, inicialização de subagentes com contexto isolado, hooks de ciclo de vida e um Session Store.

O Problema

Uma API de LLM bruta oferece apenas uma viagem de ida e volta. Um agente de produção precisa de execução de ferramentas, servidores MCP, hooks de ciclo de vida, inicialização de subagentes, persistência de sessão e propagação de traces. O Claude Agent SDK entrega essa estrutura como uma biblioteca — o mesmo harness que o Claude Code usa, exposto para agentes personalizados.

O Conceito

Client SDK vs Agent SDK

• Client SDK (anthropic). API de mensagens bruta. Você é responsável pelo loop, pelas ferramentas e pelo estado.
• Agent SDK (claude-agent-sdk). Execução integrada de ferramentas, conexões MCP, hooks, inicialização de subagentes, Session Store. O loop do Claude Code como uma biblioteca.

Ferramentas integradas

O SDK vem com mais de 10 ferramentas integradas prontas para uso: leitura/escrita de arquivos, shell, grep, glob, busca na web (fetch) e mais. Ferramentas personalizadas são registradas por meio da interface padrão de esquema de ferramentas (tool-schema).

Subagentes

Dois propósitos documentados pela Anthropic:

1. Paralelização. Executar trabalhos independentes simultaneamente. "Encontrar o arquivo de teste para cada um desses 20 módulos" representa 20 tarefas paralelas de subagentes.
2. Isolamento de contexto. Os subagentes utilizam sua própria janela de contexto; apenas os resultados retornam para o orquestrador. O limite de tokens (budget) do orquestrador é preservado.

Adições recentes ao SDK Python: list_subagents(), get_subagent_messages() para leitura de transcrições de subagentes.

Session Store

Paridade de protocolo com TypeScript:

• append(session_id, message) — adiciona um turno.
• load(session_id) — restaura a conversa.
• list_sessions() — enumera as sessões.
• delete(session_id) — exclui com efeito cascata para as sessões de subagentes.
• list_subkeys(session_id) — lista as chaves dos subagentes.

--session-mirror (flag de CLI) espelha a transcrição em um arquivo externo à medida que é transmitida (streaming), para fins de depuração.

Hooks

Hooks de ciclo de vida que você pode registrar:

• PreToolUse, PostToolUse — controlam ou auditam chamadas de ferramentas.
• SessionStart, SessionEnd — realizam a inicialização e encerramento.
• UserPromptSubmit — agem sobre a entrada do usuário antes do modelo visualizá-la.
• PreCompact — executam antes da compactação de contexto.
• Stop — realizam a limpeza na saída do agente.
• Notification — alertas de canal secundário (side-channel).

Hooks são como o pro-workflow (referência curricular da Fase 14) e sistemas semelhantes adicionam comportamentos transversais.

Contexto de trace W3C

Spans do OTel ativos no chamador se propagam para o subprocesso da CLI por meio de cabeçalhos de contexto de trace W3C. Todo o trace multiprocesso é exibido como um único trace em seu backend.

Claude Managed Agents

A alternativa hospedada (cabeçalho beta managed-agents-2026-04-01). Trabalho assíncrono de longa duração, cache de prompt integrado, compactação integrada. Troque o controle por infraestrutura gerenciada.

Onde este padrão pode falhar

• Excesso de inicialização de subagentes. Iniciar 100 subagentes para 100 tarefas minúsculas. A sobrecarga operacional (overhead) domina. Em vez disso, faça o processamento em lote (batch).
• Excesso de hooks (hook creep). Cada equipe adiciona hooks; o tempo de inicialização infla. Revise os hooks trimestralmente.
• Acúmulo de sessões. As sessões se acumulam e o tamanho aumenta. Use list_sessions com uma política de expiração.

Construa

code/main.py implementa a estrutura do SDK usando stdlib:

• Tool, ToolRegistry com read_file, write_file, list_dir integrados.
• Subagent — contexto privado, execução isolada, resultados retornados.
• SessionStore — append, load, list, delete, list_subkeys.
• Hooks — pre_tool_use, post_tool_use, session_start, session_end.
• Uma demonstração: o agente principal inicializa 3 subagentes em paralelo (cada um isolado), agrega os resultados e persiste a sessão.

Execute-o:

python3 code/main.py

O trace exibe o isolamento de contexto do subagente (o tamanho do contexto do orquestrador permanece limitado), a execução de hooks e a persistência da sessão.

Use

• Claude Agent SDK para produtos focados em Claude que desejam o formato de harness do Claude Code.
• Claude Managed Agents para trabalhos assíncronos de longa duração hospedados.
• OpenAI Agents SDK (Lição 16) para equivalentes focados em OpenAI.
• LangGraph + ferramentas personalizadas caso você prefira uma máquina de estados em formato de grafo.

Envie para Produção

outputs/skill-claude-agent-scaffold.md estrutura um aplicativo Claude Agent SDK com subagentes, hooks, Session Store, conexão de servidor MCP e propagação de traces W3C.

Exercícios

1. Adicione um inicializador de subagentes que agrupa 20 tarefas em lotes de 5 subagentes paralelos. Meça o tamanho do contexto do orquestrador em comparação com um subagente por tarefa.
2. Implemente um hook PreToolUse que limita a taxa de chamadas a write_file (5 por minuto por sessão). Monitore o comportamento.
3. Conecte list_subkeys para renderizar uma árvore de subagentes. Como fica a aparência com aninhamento profundo?
4. Migre o protótipo para o pacote Python real claude-agent-sdk. O que muda no registro de ferramentas?
5. Leia a documentação do Claude Managed Agents. Quando você mudaria de uma hospedagem própria (self-hosted) para gerenciada?

Termos Chave

Leituras Adicionais

• Visão geral do Claude Agent SDK — a versão em biblioteca do Claude Code
• Anthropic, Construindo agentes com o Claude Agent SDK — padrões de produção
• Visão geral do Claude Managed Agents — alternativa hospedada
• OpenAI Agents SDK — contraparte