Noções Básicas do Claude Agent SDK

9 exemplos para você começar com o Claude Agent SDK - 6 básicos e 3 intermediários.

Pré-requisitos

Instale o pacote Python: pip install claude-agent-sdk (TypeScript: npm install @anthropic-ai/claude-agent-sdk).
Defina uma chave de API em seu ambiente: export ANTHROPIC_API_KEY=sk-ant-....
O SDK agrupa seu próprio binário CLI internamente; você não precisa instalar o Claude Code separadamente para usá-lo.
Os exemplos abaixo usam asyncio, pois o query() do SDK Python é um gerador assíncrono.

Exemplos Básicos

1. Seu Primeiro query()

A forma mínima: um prompt, ferramentas padrão, resposta transmitida.

import asyncio
from claude_agent_sdk import query
 
async def main():
    async for message in query(prompt="Quanto é 17 * 34?"):
        print(message)
 
asyncio.run(main())

query() retorna um iterador assíncrono de mensagens, não uma única string.
Sem options passadas, o agente é executado com o conjunto de ferramentas padrão do SDK.
Cada mensagem produzida representa uma etapa do loop de uso de ferramentas subjacente, incluindo a resposta final.

Relacionado: O Modelo Mental do Claude Agent SDK - o que está acontecendo sob essa chamada

2. Escolhendo um Modelo

Escolha um modelo específico em vez do padrão do SDK.

from claude_agent_sdk import query, AgentOptions
 
options = AgentOptions(model="claude-sonnet-5")
 
async for message in query(prompt="Resuma este changelog.", options=options):
    print(message)

AgentOptions é onde a maior parte da configuração por chamada reside.
claude-sonnet-5 é o padrão balanceado atual; claude-haiku-4-5 troca qualidade por velocidade e custo.
A escolha do modelo não altera a mecânica do loop, apenas qual modelo toma cada decisão.

3. Escopo do Acesso a Ferramentas

Restrinja quais ferramentas integradas o agente pode chamar.

from claude_agent_sdk import query, AgentOptions
 
options = AgentOptions(allowed_tools=["file_edit"])
 
async for message in query(
    prompt="Corrija o erro de digitação em README.md",
    options=options,
):
    print(message)

allowed_tools é uma lista explícita de permissão; tudo o que não estiver listado não estará disponível para o loop.
Escopar apenas para file_edit significa que este agente não pode executar comandos bash ou buscar na web, mesmo que quisesse.
Comece com escopo restrito e aumente apenas quando uma tarefa realmente precisar de mais.

Relacionado: Habilitando Ferramentas de Edição de Arquivo, Bash e Web no Agent SDK - guia completo de escopo de ferramentas

4. Lendo o Diretório de Trabalho

Aponte o agente para a raiz de um projeto específico.

from claude_agent_sdk import query, AgentOptions
 
options = AgentOptions(
    cwd="/path/to/project",
    allowed_tools=["file_edit", "bash"],
)
 
async for message in query(prompt="Liste os testes que falharam.", options=options):
    print(message)

cwd limita as operações de arquivo e bash a uma árvore de diretórios específica.
Definir cwd explicitamente evita surpresas quando o SDK é executado a partir de um diretório de trabalho de processo diferente.
Combine com allowed_tools para que o agente possa inspecionar e agir nesse projeto.

5. Transmitindo Texto Conforme Ele Chega

Imprima apenas o conteúdo de texto do assistente em vez de cada tipo de mensagem.

from claude_agent_sdk import query
 
async for message in query(prompt="Explique o que este repositório faz."):
    if message.get("type") == "text":
        print(message["text"], end="", flush=True)

O fluxo de mensagens mistura eventos de texto, chamada de ferramenta e resultado de ferramenta; filtrar por type obtém apenas o texto.
A transmissão permite mostrar o progresso em um CLI ou UI em vez de esperar que todo o loop termine.
As formas exatas das mensagens são documentadas na referência do SDK; trate type como o discriminador principal.

6. Um Utilitário Síncrono de Disparo Único

Envolva query() para chamadores que não querem lidar com iteração assíncrona.

import asyncio
from claude_agent_sdk import query
 
def ask(prompt: str) -> str:
    async def _run():
        chunks = []
        async for message in query(prompt=prompt):
            if message.get("type") == "text":
                chunks.append(message["text"])
        return "".join(chunks)
    return asyncio.run(_run())
 
print(ask("Dê-me um resumo de uma frase do asyncio."))

Útil para scripts ou notebooks que apenas desejam uma string final de volta.
Este padrão descarta eventos intermediários de chamada de ferramenta; use o fluxo bruto quando precisar mostrá-los ou registrá-los.
O código de produção geralmente mantém a forma assíncrona para que possa ser executado dentro de um loop de eventos existente.

Exemplos Intermediários

7. Combinando Ferramentas com um Modo de Permissão

Habilite várias ferramentas integradas enquanto exige aprovação em ações arriscadas.

from claude_agent_sdk import query, AgentOptions
 
options = AgentOptions(
    allowed_tools=["file_edit", "bash", "web_search"],
    permission_mode="default",  # pausa antes de ações destrutivas
)
 
async for message in query(
    prompt="Investigue a falha na execução do CI e proponha uma correção.",
    options=options,
):
    print(message)

permission_mode="default" mantém as decisões de uso de ferramentas do loop intactas, mas insere um portão de aprovação antes de chamadas destrutivas.
Três ferramentas são habilitadas juntas aqui porque a tarefa abrange genuinamente leitura (bash), correção (file_edit) e pesquisa (web_search).
Esta é a forma que a maioria dos agentes "investigar e corrigir" assume.

Relacionado: Adicionando Pontos de Verificação Human-in-the-Loop a um Fluxo de Trabalho do Agent SDK - portões de aprovação em profundidade

8. Retomando uma Sessão

Continue uma execução anterior em vez de começar com um contexto em branco.

from claude_agent_sdk import query, AgentOptions
 
first = query(prompt="Comece a revisar src/orders/", options=AgentOptions())
session_id = None
async for message in first:
    if message.get("type") == "session_start":
        session_id = message["session_id"]
 
# mais tarde, possivelmente em um novo processo
resume_options = AgentOptions(resume=session_id)
async for message in query(prompt="Continue de onde parou.", options=resume_options):
    print(message)

O identificador da sessão captura o histórico de conversas e resultados de ferramentas da primeira execução.
Passá-lo via resume em uma chamada posterior continua o loop com esse histórico já em contexto.
Isso é o que torna tarefas de agente de longa duração e multi-etapas práticas em invocações de processo separadas.

Relacionado: Persistindo Sessões Entre Execuções com o Claude Agent SDK - padrões de armazenamento e retomada

9. Delegando um Trabalho a um Subagente

Crie um agente filho isolado para uma parte de uma tarefa maior.

from claude_agent_sdk import query, AgentOptions, SubagentConfig
 
options = AgentOptions(
    allowed_tools=["file_edit", "bash"],
    subagents=[
        SubagentConfig(
            name="test-runner",
            allowed_tools=["bash"],
            description="Executa a suíte de testes e relata apenas as falhas.",
        )
    ],
)
 
async for message in query(
    prompt="Use o subagente test-runner para verificar se a suíte passa, em seguida, corrija quaisquer falhas.",
    options=options,
):
    print(message)

O subagente recebe seu próprio escopo de ferramentas (bash apenas) e seu próprio contexto isolado, separado do principal.
O agente principal decide quando invocar o subagente, da mesma forma que decide chamar qualquer outra ferramenta.
Use isso quando o raciocínio intermediário de uma subtarefa puder poluir o contexto do principal.

Relacionado: Delegando Trabalho a Subagentes no Claude Agent SDK - paralelizando fluxos de trabalho independentes

Versões da Stack: Escrito contra a linha de modelos Claude atual em aproximadamente junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5 - e o Claude Agent SDK (último lançamento, Python e TypeScript). Nomes de modelos, versões de SDK e preços mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.

Noções Básicas do Claude Agent SDK

9 exemplos para você começar com o Claude Agent SDK - 6 básicos e 3 intermediários.

Pré-requisitos

Instale o pacote Python: pip install claude-agent-sdk (TypeScript: npm install @anthropic-ai/claude-agent-sdk).
Defina uma chave de API em seu ambiente: export ANTHROPIC_API_KEY=sk-ant-....
O SDK agrupa seu próprio binário CLI internamente; você não precisa instalar o Claude Code separadamente para usá-lo.
Os exemplos abaixo usam asyncio, pois o query() do SDK Python é um gerador assíncrono.

Exemplos Básicos

1. Seu Primeiro query()

A forma mínima: um prompt, ferramentas padrão, resposta transmitida.

import asyncio
from claude_agent_sdk import query
 
async def main():
    async for message in query(prompt="Quanto é 17 * 34?"):
        print(message)
 
asyncio.run(main())

query() retorna um iterador assíncrono de mensagens, não uma única string.
Sem options passadas, o agente é executado com o conjunto de ferramentas padrão do SDK.
Cada mensagem produzida representa uma etapa do loop de uso de ferramentas subjacente, incluindo a resposta final.

Relacionado: O Modelo Mental do Claude Agent SDK - o que está acontecendo sob essa chamada

2. Escolhendo um Modelo

Escolha um modelo específico em vez do padrão do SDK.

from claude_agent_sdk import query, AgentOptions
 
options = AgentOptions(model="claude-sonnet-5")
 
async for message in query(prompt="Resuma este changelog.", options=options):
    print(message)

AgentOptions é onde a maior parte da configuração por chamada reside.
claude-sonnet-5 é o padrão balanceado atual; claude-haiku-4-5 troca qualidade por velocidade e custo.
A escolha do modelo não altera a mecânica do loop, apenas qual modelo toma cada decisão.

3. Escopo do Acesso a Ferramentas

Restrinja quais ferramentas integradas o agente pode chamar.

from claude_agent_sdk import query, AgentOptions
 
options = AgentOptions(allowed_tools=["file_edit"])
 
async for message in query(
    prompt="Corrija o erro de digitação em README.md",
    options=options,
):
    print(message)

allowed_tools é uma lista explícita de permissão; tudo o que não estiver listado não estará disponível para o loop.
Escopar apenas para file_edit significa que este agente não pode executar comandos bash ou buscar na web, mesmo que quisesse.
Comece com escopo restrito e aumente apenas quando uma tarefa realmente precisar de mais.

Relacionado: Habilitando Ferramentas de Edição de Arquivo, Bash e Web no Agent SDK - guia completo de escopo de ferramentas

4. Lendo o Diretório de Trabalho

Aponte o agente para a raiz de um projeto específico.

from claude_agent_sdk import query, AgentOptions
 
options = AgentOptions(
    cwd="/path/to/project",
    allowed_tools=["file_edit", "bash"],
)
 
async for message in query(prompt="Liste os testes que falharam.", options=options):
    print(message)

cwd limita as operações de arquivo e bash a uma árvore de diretórios específica.
Definir cwd explicitamente evita surpresas quando o SDK é executado a partir de um diretório de trabalho de processo diferente.
Combine com allowed_tools para que o agente possa inspecionar e agir nesse projeto.

5. Transmitindo Texto Conforme Ele Chega

Imprima apenas o conteúdo de texto do assistente em vez de cada tipo de mensagem.

from claude_agent_sdk import query
 
async for message in query(prompt="Explique o que este repositório faz."):
    if message.get("type") == "text":
        print(message["text"], end="", flush=True)

O fluxo de mensagens mistura eventos de texto, chamada de ferramenta e resultado de ferramenta; filtrar por type obtém apenas o texto.
A transmissão permite mostrar o progresso em um CLI ou UI em vez de esperar que todo o loop termine.
As formas exatas das mensagens são documentadas na referência do SDK; trate type como o discriminador principal.

6. Um Utilitário Síncrono de Disparo Único

Envolva query() para chamadores que não querem lidar com iteração assíncrona.

import asyncio
from claude_agent_sdk import query
 
def ask(prompt: str) -> str:
    async def _run():
        chunks = []
        async for message in query(prompt=prompt):
            if message.get("type") == "text":
                chunks.append(message["text"])
        return "".join(chunks)
    return asyncio.run(_run())
 
print(ask("Dê-me um resumo de uma frase do asyncio."))

Útil para scripts ou notebooks que apenas desejam uma string final de volta.
Este padrão descarta eventos intermediários de chamada de ferramenta; use o fluxo bruto quando precisar mostrá-los ou registrá-los.
O código de produção geralmente mantém a forma assíncrona para que possa ser executado dentro de um loop de eventos existente.

Exemplos Intermediários

7. Combinando Ferramentas com um Modo de Permissão

Habilite várias ferramentas integradas enquanto exige aprovação em ações arriscadas.

from claude_agent_sdk import query, AgentOptions
 
options = AgentOptions(
    allowed_tools=["file_edit", "bash", "web_search"],
    permission_mode="default",  # pausa antes de ações destrutivas
)
 
async for message in query(
    prompt="Investigue a falha na execução do CI e proponha uma correção.",
    options=options,
):
    print(message)

permission_mode="default" mantém as decisões de uso de ferramentas do loop intactas, mas insere um portão de aprovação antes de chamadas destrutivas.
Três ferramentas são habilitadas juntas aqui porque a tarefa abrange genuinamente leitura (bash), correção (file_edit) e pesquisa (web_search).
Esta é a forma que a maioria dos agentes "investigar e corrigir" assume.

Relacionado: Adicionando Pontos de Verificação Human-in-the-Loop a um Fluxo de Trabalho do Agent SDK - portões de aprovação em profundidade

8. Retomando uma Sessão

Continue uma execução anterior em vez de começar com um contexto em branco.

from claude_agent_sdk import query, AgentOptions
 
first = query(prompt="Comece a revisar src/orders/", options=AgentOptions())
session_id = None
async for message in first:
    if message.get("type") == "session_start":
        session_id = message["session_id"]
 
# mais tarde, possivelmente em um novo processo
resume_options = AgentOptions(resume=session_id)
async for message in query(prompt="Continue de onde parou.", options=resume_options):
    print(message)

O identificador da sessão captura o histórico de conversas e resultados de ferramentas da primeira execução.
Passá-lo via resume em uma chamada posterior continua o loop com esse histórico já em contexto.
Isso é o que torna tarefas de agente de longa duração e multi-etapas práticas em invocações de processo separadas.

Relacionado: Persistindo Sessões Entre Execuções com o Claude Agent SDK - padrões de armazenamento e retomada

9. Delegando um Trabalho a um Subagente

Crie um agente filho isolado para uma parte de uma tarefa maior.

from claude_agent_sdk import query, AgentOptions, SubagentConfig
 
options = AgentOptions(
    allowed_tools=["file_edit", "bash"],
    subagents=[
        SubagentConfig(
            name="test-runner",
            allowed_tools=["bash"],
            description="Executa a suíte de testes e relata apenas as falhas.",
        )
    ],
)
 
async for message in query(
    prompt="Use o subagente test-runner para verificar se a suíte passa, em seguida, corrija quaisquer falhas.",
    options=options,
):
    print(message)

O subagente recebe seu próprio escopo de ferramentas (bash apenas) e seu próprio contexto isolado, separado do principal.
O agente principal decide quando invocar o subagente, da mesma forma que decide chamar qualquer outra ferramenta.
Use isso quando o raciocínio intermediário de uma subtarefa puder poluir o contexto do principal.

Relacionado: Delegando Trabalho a Subagentes no Claude Agent SDK - paralelizando fluxos de trabalho independentes

Versões da Stack: Escrito contra a linha de modelos Claude atual em aproximadamente junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5 - e o Claude Agent SDK (último lançamento, Python e TypeScript). Nomes de modelos, versões de SDK e preços mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.

Noções Básicas do Claude Agent SDK

Buscar na documentação

Noções Básicas do Claude Agent SDK