Documentation 2026-06-13 21:59 UTC to 2026-06-15 23:02 UTC

16 16 

17Cada sessão de agente segue o mesmo ciclo:17Cada sessão de agente segue o mesmo ciclo:

18 18 

19<img src="https://mintcdn.com/claude-code/gvy2DIUELtNA8qD3/images/agent-loop-diagram.svg?fit=max&auto=format&n=gvy2DIUELtNA8qD3&q=85&s=192e1bd6c8a2950a16e5ee0b94e27e26" alt="Agent loop: prompt entra, Claude avalia, ramifica para chamadas de ferramentas ou resposta final" width="680" height="150" data-path="images/agent-loop-diagram.svg" />19<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/agent-loop-diagram.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=1c6e8f28d80dba14a7287419656f1237" alt="Agent loop: prompt entra, Claude avalia, ramifica para chamadas de ferramentas ou resposta final" width="720" height="212" data-path="images/agent-loop-diagram.svg" />

20 20 

211. **Receber prompt.** Claude recebe seu prompt, junto com o prompt do sistema, definições de ferramentas e histórico de conversa. O SDK produz uma [`SystemMessage`](#message-types) com subtipo `"init"` contendo metadados da sessão.211. **Receber prompt.** Claude recebe seu prompt, junto com o prompt do sistema, definições de ferramentas e histórico de conversa. O SDK produz uma [`SystemMessage`](#message-types) com subtipo `"init"` contendo metadados da sessão.

222. **Avaliar e responder.** Claude avalia o estado atual e determina como proceder. Pode responder com texto, solicitar uma ou mais chamadas de ferramentas, ou ambos. O SDK produz uma [`AssistantMessage`](#message-types) contendo o texto e quaisquer solicitações de chamadas de ferramentas.222. **Avaliar e responder.** Claude avalia o estado atual e determina como proceder. Pode responder com texto, solicitar uma ou mais chamadas de ferramentas, ou ambos. O SDK produz uma [`AssistantMessage`](#message-types) contendo o texto e quaisquer solicitações de chamadas de ferramentas.

39 39 

40O diagrama a seguir mostra o fluxo de mensagens de uma única chamada `query()`, com uso de tokens relatado em cada etapa e a estimativa cumulativa no final:40O diagrama a seguir mostra o fluxo de mensagens de uma única chamada `query()`, com uso de tokens relatado em cada etapa e a estimativa cumulativa no final:

41 41 

42<img src="https://mintcdn.com/claude-code/Dujg43sxTkuhSELI/images/agent-sdk/message-usage-flow.svg?fit=max&auto=format&n=Dujg43sxTkuhSELI&q=85&s=c542f51ff58547ef9c0e57b16d03f33c" alt="Diagrama mostrando uma query produzindo duas etapas de mensagens. A Etapa 1 tem quatro mensagens do assistente compartilhando o mesmo ID e uso (contar uma vez), a Etapa 2 tem uma mensagem do assistente com um novo ID, e a mensagem de resultado final mostra o total_cost_usd estimado." width="760" height="520" data-path="images/agent-sdk/message-usage-flow.svg" />42<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/agent-sdk/message-usage-flow.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=68497aee338e01cc745323af7aea378e" alt="Diagrama mostrando uma query produzindo duas etapas de mensagens. A Etapa 1 tem quatro mensagens do assistente compartilhando o mesmo ID e uso (contar uma vez), a Etapa 2 tem uma mensagem do assistente com um novo ID, e a mensagem de resultado final mostra o total_cost_usd estimado." width="760" height="520" data-path="images/agent-sdk/message-usage-flow.svg" />

43 43 

44<Steps>44<Steps>

45 <Step title="Cada etapa produz mensagens do assistente">45 <Step title="Cada etapa produz mensagens do assistente">

22 22 

23Cada decisão de hospedagem nesta página segue de como o SDK executa o agente. Quando seu código chama `query()`, o SDK spawna um processo CLI `claude` separado e se comunica com ele via stdio. Esse subprocess possui o shell, o diretório de trabalho e os transcripts de sessão JSONL no disco local.23Cada decisão de hospedagem nesta página segue de como o SDK executa o agente. Quando seu código chama `query()`, o SDK spawna um processo CLI `claude` separado e se comunica com ele via stdio. Esse subprocess possui o shell, o diretório de trabalho e os transcripts de sessão JSONL no disco local.

24 24 

25<img src="https://mintcdn.com/claude-code/Akpoo6g0xDlAmvHv/images/agent-sdk/hosting-subprocess.svg?fit=max&auto=format&n=Akpoo6g0xDlAmvHv&q=85&s=d348cc9687d47e0bc954075fd88d0e60" alt="Fluxo de solicitação: cliente para seu aplicativo, que spawna um subprocess CLI claude via stdio dentro do container; o subprocess escreve no disco local e chama api.anthropic.com via HTTPS" width="920" height="220" data-path="images/agent-sdk/hosting-subprocess.svg" />25<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/agent-sdk/hosting-subprocess.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=9dac857ca9d3b1410c3734900c386004" alt="Fluxo de solicitação: cliente para seu aplicativo, que spawna um subprocess CLI claude via stdio dentro do container; o subprocess escreve no disco local e chama api.anthropic.com via HTTPS" width="920" height="220" data-path="images/agent-sdk/hosting-subprocess.svg" />

26 26 

27Uma sessão de agente mapeia para um subprocess. Executar N sessões concorrentes significa N subprocessos, cada um com sua própria árvore de processos e arquivo de transcript. Por padrão, todos herdam o diretório de trabalho do seu aplicativo, então passe `cwd` em cada chamada `query()` quando as sessões precisarem de sistemas de arquivos separados:27Uma sessão de agente mapeia para um subprocess. Executar N sessões concorrentes significa N subprocessos, cada um com sua própria árvore de processos e arquivo de transcript. Por padrão, todos herdam o diretório de trabalho do seu aplicativo, então passe `cwd` em cada chamada `query()` quando as sessões precisarem de sistemas de arquivos separados:

28 28 

6 6 

7> Construa agentes de IA em produção com Claude Code como uma biblioteca7> Construa agentes de IA em produção com Claude Code como uma biblioteca

8 8 

9<Note>

10 Starting June 15, 2026, Agent SDK and `claude -p` usage on subscription plans will draw from a new monthly Agent SDK credit, separate from your interactive usage limits. See [Use the Claude Agent SDK with your Claude plan](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan) for details.

11</Note>

12 

13Construa agentes de IA que leem arquivos autonomamente, executam comandos, pesquisam na web, editam código e muito mais. O Agent SDK oferece as mesmas ferramentas, loop de agente e gerenciamento de contexto que alimentam Claude Code, programável em Python e TypeScript.9Construa agentes de IA que leem arquivos autonomamente, executam comandos, pesquisam na web, editam código e muito mais. O Agent SDK oferece as mesmas ferramentas, loop de agente e gerenciamento de contexto que alimentam Claude Code, programável em Python e TypeScript.

14 10 

15<CodeGroup>11<CodeGroup>

40 </Step>40 </Step>

41</Steps>41</Steps>

42 42 

43<img src="https://mintcdn.com/claude-code/FEspvVUyRuaWjm0s/images/agent-sdk/permissions-flow.svg?fit=max&auto=format&n=FEspvVUyRuaWjm0s&q=85&s=a1759b0cf4541281a9fdd8f5348228e8" alt="Diagrama de fluxo de avaliação de permissões" width="920" height="260" data-path="images/agent-sdk/permissions-flow.svg" />43<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/agent-sdk/permissions-flow.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=cc94220087262cd48c9b64a14c4e1c2c" alt="Diagrama de fluxo de avaliação de permissões" width="1024" height="260" data-path="images/agent-sdk/permissions-flow.svg" />

44 44 

45Esta página se concentra em **regras de permitir e negar** e **modos de permissão**. Para os outros passos:45Esta página se concentra em **regras de permitir e negar** e **modos de permissão**. Para os outros passos:

46 46 

159 Gere um token de longa duração159 Gere um token de longa duração

160</h3>160</h3>

161 161 

162<Note>

163 Starting June 15, 2026, Agent SDK and `claude -p` usage on subscription plans will draw from a new monthly Agent SDK credit, separate from your interactive usage limits. See [Use the Claude Agent SDK with your Claude plan](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan) for details.

164</Note>

165 

166Para pipelines de CI, scripts ou outros ambientes onde login do navegador interativo não está disponível, gere um token OAuth de um ano com `claude setup-token`:162Para pipelines de CI, scripts ou outros ambientes onde login do navegador interativo não está disponível, gere um token OAuth de um ano com `claude setup-token`:

167 163 

168```bash theme={null}164```bash theme={null}

83 83 

84O diagrama abaixo mostra como Claude Code se conecta a serviços externos durante a instalação e operação normal. Linhas sólidas indicam conexões obrigatórias, enquanto linhas tracejadas representam fluxos de dados opcionais ou iniciados pelo usuário.84O diagrama abaixo mostra como Claude Code se conecta a serviços externos durante a instalação e operação normal. Linhas sólidas indicam conexões obrigatórias, enquanto linhas tracejadas representam fluxos de dados opcionais ou iniciados pelo usuário.

85 85 

86<img src="https://mintcdn.com/claude-code/RcOyXc06Ja8cuvMZ/images/claude-code-data-flow.svg?fit=max&auto=format&n=RcOyXc06Ja8cuvMZ&q=85&s=b5be40abf333defe984993af89546c19" alt="Diagram showing Claude Code's external connections: install/update connects to the distribution server, and user requests connect to Anthropic services including Console auth, public-api, and optionally metrics, Sentry, and bug reporting" width="720" height="520" data-path="images/claude-code-data-flow.svg" />86<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/claude-code-data-flow.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=5b1131530bdfdd415700a0cb4d4070c4" alt="Diagram showing Claude Code's external connections: install/update connects to the distribution server, and user requests connect to Anthropic services including Console auth, public-api, and optionally metrics, Sentry, and bug reporting" width="720" height="520" data-path="images/claude-code-data-flow.svg" />

87 87 

88Claude Code é executado localmente. Para interagir com o LLM, Claude Code envia dados pela rede. Esses dados incluem todos os prompts do usuário e saídas do modelo, criptografados em trânsito via TLS 1.2+. Claude Code é compatível com a maioria dos VPNs e proxies LLM populares.88Claude Code é executado localmente. Para interagir com o LLM, Claude Code envia dados pela rede. Esses dados incluem todos os prompts do usuário e saídas do modelo, criptografados em trânsito via TLS 1.2+. Claude Code é compatível com a maioria dos VPNs e proxies LLM populares.

89 89 

247 247 

248Cada recurso carrega em diferentes pontos em sua sessão. As abas abaixo explicam quando cada um carrega e o que entra em contexto.248Cada recurso carrega em diferentes pontos em sua sessão. As abas abaixo explicam quando cada um carrega e o que entra em contexto.

249 249 

250<img src="https://mintcdn.com/claude-code/6yTCYq1p37ZB8-CQ/images/context-loading.svg?fit=max&auto=format&n=6yTCYq1p37ZB8-CQ&q=85&s=5a58ce953a35a2412892015e2ad6cb67" alt="Carregamento de contexto: CLAUDE.md carrega no início da sessão e permanece em cada requisição. Nomes de ferramentas MCP carregam no início com esquemas completos adiados até o uso. Skills carregam descrições no início, conteúdo completo na invocação. Subagents obtêm contexto isolado. Hooks são executados externamente." width="720" height="410" data-path="images/context-loading.svg" />250<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/context-loading.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=aab139e750494a237ae2e0c8f9139b0a" alt="Carregamento de contexto: CLAUDE.md carrega no início da sessão e permanece em cada requisição. Nomes de ferramentas MCP carregam no início com esquemas completos adiados até o uso. Skills carregam descrições no início, conteúdo completo na invocação. Subagents obtêm contexto isolado. Hooks são executados externamente." width="720" height="382" data-path="images/context-loading.svg" />

251 251 

252<Tabs>252<Tabs>

253 <Tab title="CLAUDE.md">253 <Tab title="CLAUDE.md">

6 6 

7> Use o Agent SDK para executar Claude Code programaticamente a partir da CLI, Python ou TypeScript.7> Use o Agent SDK para executar Claude Code programaticamente a partir da CLI, Python ou TypeScript.

8 8 

9<Note>

10 Starting June 15, 2026, Agent SDK and `claude -p` usage on subscription plans will draw from a new monthly Agent SDK credit, separate from your interactive usage limits. See [Use the Claude Agent SDK with your Claude plan](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan) for details.

11</Note>

12 

13O [Agent SDK](/pt/agent-sdk/overview) oferece as mesmas ferramentas, loop de agente e gerenciamento de contexto que alimentam Claude Code. Está disponível como uma CLI para scripts e CI/CD, ou como pacotes [Python](/pt/agent-sdk/python) e [TypeScript](/pt/agent-sdk/typescript) para controle programático completo.9O [Agent SDK](/pt/agent-sdk/overview) oferece as mesmas ferramentas, loop de agente e gerenciamento de contexto que alimentam Claude Code. Está disponível como uma CLI para scripts e CI/CD, ou como pacotes [Python](/pt/agent-sdk/python) e [TypeScript](/pt/agent-sdk/typescript) para controle programático completo.

14 10 

15Para executar Claude Code em modo não interativo, passe `-p` com seu prompt e qualquer [opção de CLI](/pt/cli-reference):11Para executar Claude Code em modo não interativo, passe `-p` com seu prompt e qualquer [opção de CLI](/pt/cli-reference):

108Agora suponha que o Claude Code decida executar `Bash "rm -rf /tmp/build"`. Aqui está o que acontece:108Agora suponha que o Claude Code decida executar `Bash "rm -rf /tmp/build"`. Aqui está o que acontece:

109 109 

110<Frame>110<Frame>

111 <img src="https://mintcdn.com/claude-code/-tYw1BD_DEqfyyOZ/images/hook-resolution.svg?fit=max&auto=format&n=-tYw1BD_DEqfyyOZ&q=85&s=c73ebc1eeda2037570427d7af1e0a891" alt="Fluxo de resolução de hook: evento PreToolUse dispara, matcher verifica correspondência de Bash, condição if verifica correspondência de Bash(rm *), manipulador de hook executa, resultado retorna ao Claude Code" width="930" height="290" data-path="images/hook-resolution.svg" />111 <img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/hook-resolution.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=be0bf3053550c26de5f54cd64674c197" alt="Fluxo de resolução de hook: evento PreToolUse dispara, matcher verifica correspondência de Bash, condição if verifica correspondência de Bash(rm *), manipulador de hook executa, resultado retorna ao Claude Code" width="930" height="270" data-path="images/hook-resolution.svg" />

112</Frame>112</Frame>

113 113 

114<Steps>114<Steps>

16 16 

17Quando você dá uma tarefa a Claude, ele trabalha através de três fases: **reunir contexto**, **tomar ação** e **verificar resultados**. Essas fases se misturam. Claude usa ferramentas ao longo do processo, seja pesquisando arquivos para entender seu código, editando para fazer alterações ou executando testes para verificar seu trabalho.17Quando você dá uma tarefa a Claude, ele trabalha através de três fases: **reunir contexto**, **tomar ação** e **verificar resultados**. Essas fases se misturam. Claude usa ferramentas ao longo do processo, seja pesquisando arquivos para entender seu código, editando para fazer alterações ou executando testes para verificar seu trabalho.

18 18 

19<img src="https://mintcdn.com/claude-code/c5r9_6tjPMzFdDDT/images/agentic-loop.svg?fit=max&auto=format&n=c5r9_6tjPMzFdDDT&q=85&s=5f1827dec8539f38adee90ead3a85a38" alt="O loop agentic: Seu prompt leva Claude a reunir contexto, tomar ação, verificar resultados e repetir até que a tarefa seja concluída. Você pode interromper em qualquer ponto." width="720" height="280" data-path="images/agentic-loop.svg" />19<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/agentic-loop.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=4a30fb7ce2815012a9f27c955e2c6bb0" alt="O loop agentic: Seu prompt leva Claude a reunir contexto, tomar ação, verificar resultados e repetir até que a tarefa seja concluída. Você pode interromper em qualquer ponto." width="720" height="280" data-path="images/agentic-loop.svg" />

20 20 

21O loop se adapta ao que você pede. Uma pergunta sobre sua base de código pode precisar apenas de coleta de contexto. Uma correção de bug passa por todas as três fases repetidamente. Uma refatoração pode envolver verificação extensiva. Claude decide o que cada etapa requer com base no que aprendeu da etapa anterior, encadeando dezenas de ações e se autocorrigindo ao longo do caminho.21O loop se adapta ao que você pede. Uma pergunta sobre sua base de código pode precisar apenas de coleta de contexto. Uma correção de bug passa por todas as três fases repetidamente. Uma refatoração pode envolver verificação extensiva. Claude decide o que cada etapa requer com base no que aprendeu da etapa anterior, encadeando dezenas de ações e se autocorrigindo ao longo do caminho.

22 22 

130 130 

131Retomar uma sessão com `claude --continue` ou `claude --resume` reabre-a sob o mesmo ID de sessão e anexa novas mensagens à conversa existente. Bifurcar com `--fork-session` ou `/branch` copia o histórico em um novo ID de sessão, deixando o original inalterado.131Retomar uma sessão com `claude --continue` ou `claude --resume` reabre-a sob o mesmo ID de sessão e anexa novas mensagens à conversa existente. Bifurcar com `--fork-session` ou `/branch` copia o histórico em um novo ID de sessão, deixando o original inalterado.

132 132 

133<img src="https://mintcdn.com/claude-code/c5r9_6tjPMzFdDDT/images/session-continuity.svg?fit=max&auto=format&n=c5r9_6tjPMzFdDDT&q=85&s=fa41d12bfb57579cabfeece907151d30" alt="Continuidade de sessão: retomar continua a mesma sessão, bifurcar cria um novo branch com um novo ID." width="560" height="280" data-path="images/session-continuity.svg" />133<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/session-continuity.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=04ed0984a58e4127e05b3640265241a3" alt="Continuidade de sessão: retomar continua a mesma sessão, bifurcar cria um novo branch com um novo ID." width="560" height="280" data-path="images/session-continuity.svg" />

134 134 

135Para as flags de retomada, o seletor `/resume`, nomeação e o que acontece quando a mesma sessão está aberta em dois terminais, consulte [Gerenciar sessões](/pt/sessions).135Para as flags de retomada, o seletor `/resume`, nomeação e o que acontece quando a mesma sessão está aberta em dois terminais, consulte [Gerenciar sessões](/pt/sessions).

136 136 

6 6 

7> Acordos legais, certificações de conformidade e informações de segurança para Claude Code.7> Acordos legais, certificações de conformidade e informações de segurança para Claude Code.

8 8 

9<Note>

10 Starting June 15, 2026, Agent SDK and `claude -p` usage on subscription plans will draw from a new monthly Agent SDK credit, separate from your interactive usage limits. See [Use the Claude Agent SDK with your Claude plan](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan) for details.

11</Note>

12 

13<h2 id="legal-agreements">9<h2 id="legal-agreements">

14 Acordos legais10 Acordos legais

15</h2>11</h2>