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
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. Para entender o raciocínio por trás do design do harness de agente, consulte [A harness for every task: dynamic workflows in Claude Code](https://claude.com/blog/a-harness-for-every-task-dynamic-workflows-in-claude-code) no blog.9Um agente é uma aplicação que completa uma tarefa planejando seus próprios passos e chamando ferramentas que leem arquivos, executam comandos ou editam código. O Agent SDK oferece as mesmas ferramentas, [loop de agente](/docs/pt/agent-sdk/agent-loop), e gerenciamento de contexto que alimentam Claude Code, programável em Python e TypeScript.
10 10
11<CodeGroup>11<h2 id="compare-the-agent-sdk-to-other-claude-tools">
12 ```python Python theme={null}12 Compare o Agent SDK com outras ferramentas Claude
13 import asyncio
14 from claude_agent_sdk import query, ClaudeAgentOptions
15
16
17 async def main():
18 async for message in query(
19 prompt="Find and fix the bug in auth.py",
20 options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
21 ):
22 print(message) # Claude reads the file, finds the bug, edits it
23
24
25 asyncio.run(main())
26 ```
27
28 ```typescript TypeScript theme={null}
29 import { query } from "@anthropic-ai/claude-agent-sdk";
30
31 for await (const message of query({
32 prompt: "Find and fix the bug in auth.ts",
33 options: { allowedTools: ["Read", "Edit", "Bash"] }
34 })) {
35 console.log(message); // Claude reads the file, finds the bug, edits it
36 }
37 ```
38</CodeGroup>
39
40O Agent SDK inclui ferramentas integradas para ler arquivos, executar comandos e editar código, para que seu agente possa começar a trabalhar imediatamente sem você implementar a execução de ferramentas. Mergulhe no guia de início rápido ou explore agentes reais construídos com o SDK:
41
42<CardGroup cols={2}>
43 <Card title="Guia de Início Rápido" icon="play" href="/pt/agent-sdk/quickstart">
44 Construa um agente de correção de bugs em minutos
45 </Card>
46
47 <Card title="Agentes de exemplo" icon="star" href="https://github.com/anthropics/claude-agent-sdk-demos">
48 Assistente de email, agente de pesquisa e muito mais
49 </Card>
50</CardGroup>
51
52<h2 id="get-started">
53 Comece agora
54</h2>13</h2>
55 14
56<Steps>15O Agent SDK, a CLI, o Client SDK e Managed Agents atendem a diferentes necessidades. Use a tabela para encontrar aquele que corresponde ao que você está construindo.
57 <Step title="Instale o SDK">
58 <Tabs>
59 <Tab title="TypeScript">
60 ```bash theme={null}
61 npm install @anthropic-ai/claude-agent-sdk
62 ```
63 </Tab>
64
65 <Tab title="Python (uv)">
66 [uv](https://docs.astral.sh/uv/) é um gerenciador de pacotes Python rápido que lida com ambientes virtuais automaticamente:
67
68 ```bash theme={null}
69 uv init
70 uv add claude-agent-sdk
71 ```
72 </Tab>
73
74 <Tab title="Python (pip)">
75 Crie e ative um ambiente virtual, depois instale o pacote. Instalar em um ambiente virtual evita a falha `error: externally-managed-environment` que o Python do sistema em instalações recentes do Debian, Ubuntu e Homebrew retorna para `pip install` fora de um venv.
76
77 No macOS ou Linux:
78
79 ```bash theme={null}
80 python3 -m venv .venv
81 source .venv/bin/activate
82 pip install claude-agent-sdk
83 ```
84
85 No Windows:
86
87 ```powershell theme={null}
88 py -m venv .venv
89 .venv\Scripts\Activate.ps1
90 pip install claude-agent-sdk
91 ```
92
93 Se o PowerShell bloquear `Activate.ps1` com um erro de política de execução, execute `Set-ExecutionPolicy -Scope Process RemoteSigned` primeiro.
94
95 O pacote Python requer Python 3.10 ou posterior. Se o pip relatar `No matching distribution found for claude-agent-sdk`, seu interpretador é mais antigo que 3.10. Execute `python3 --version` no macOS ou Linux, ou `py --version` no Windows, para verificar.
96 </Tab>
97 </Tabs>
98
99 <Note>
100 O SDK TypeScript agrupa um binário nativo do Claude Code para sua plataforma como uma dependência opcional, portanto você não precisa instalar Claude Code separadamente.
101 </Note>
102 </Step>
103
104 <Step title="Defina sua chave de API">
105 Obtenha uma chave de API do [Console](https://platform.claude.com/), depois defina-a como uma variável de ambiente.
106
107 No macOS ou Linux:
108
109 ```bash theme={null}
110 export ANTHROPIC_API_KEY=sk-ant-xxxxx
111 ```
112
113 No Windows PowerShell:
114
115 ```powershell theme={null}
116 $env:ANTHROPIC_API_KEY = "sk-ant-xxxxx"
117 ```
118
119 O SDK também suporta autenticação via provedores de API de terceiros:
120
121 * **Amazon Bedrock**: defina a variável de ambiente `CLAUDE_CODE_USE_BEDROCK=1` e configure as credenciais da AWS
122 * **Claude Platform on AWS**: defina `CLAUDE_CODE_USE_ANTHROPIC_AWS=1` e `ANTHROPIC_AWS_WORKSPACE_ID`, depois configure as credenciais da AWS
123 * **Google Cloud's Agent Platform**: defina a variável de ambiente `CLAUDE_CODE_USE_VERTEX=1` e configure as credenciais do Google Cloud
124 * **Microsoft Azure**: defina a variável de ambiente `CLAUDE_CODE_USE_FOUNDRY=1` e configure as credenciais do Azure
125
126 Consulte os guias de configuração para [Amazon Bedrock](/pt/amazon-bedrock), [Claude Platform on AWS](/pt/claude-platform-on-aws), [Google Cloud's Agent Platform](/pt/google-vertex-ai) ou [Microsoft Foundry](/pt/microsoft-foundry) para obter detalhes.
127
128 <Note>
129 A menos que previamente aprovado, a Anthropic não permite que desenvolvedores terceirizados ofereçam login claude.ai ou limites de taxa para seus produtos, incluindo agentes construídos no Claude Agent SDK. Use os métodos de autenticação de chave de API descritos neste documento.
130 </Note>
131 </Step>
132 16
133 <Step title="Execute seu primeiro agente">17| Se você está... | Use | Por quê |
134 Este exemplo cria um agente que lista arquivos em seu diretório atual usando ferramentas integradas.18| ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
19| Construindo um agente sem implementar o loop de ferramentas você mesmo | **Agent SDK** | Uma biblioteca que executa o loop do agente em seu próprio processo, em Python ou TypeScript. |
20| Fazendo desenvolvimento interativo ou executando tarefas únicas de um terminal | [**Claude Code CLI**](/docs/pt/overview) | A interface do terminal, construída para uso interativo diário. |
21| Chamando a API diretamente e implementando o loop de ferramentas você mesmo | [**Client SDK**](https://platform.claude.com/docs/en/api/client-sdks) | Acesso direto à API Anthropic em vez de Claude Code. Você implementa o loop de ferramentas você mesmo. |
22| Executando agentes de longa duração ou assíncronos sem gerenciar sua própria infraestrutura de sandbox ou sessão | [**Managed Agents**](https://platform.claude.com/docs/en/managed-agents/overview) | API REST hospedada, um produto separado do Agent SDK. Anthropic executa o agente e o sandbox. |
135 23
136 <CodeGroup>24O SDK está disponível como uma biblioteca apenas para Python e TypeScript. Para conduzir o mesmo loop de agente de outro idioma, [execute a CLI como um subprocesso](/docs/pt/headless) com a flag `-p` e `--output-format json`.
137 ```python Python theme={null}
138 import asyncio
139 from claude_agent_sdk import query, ClaudeAgentOptions
140
141
142 async def main():
143 async for message in query(
144 prompt="What files are in this directory?",
145 options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]),
146 ):
147 if hasattr(message, "result"):
148 print(message.result)
149
150
151 asyncio.run(main())
152 ```
153
154 ```typescript TypeScript theme={null}
155 import { query } from "@anthropic-ai/claude-agent-sdk";
156
157 for await (const message of query({
158 prompt: "What files are in this directory?",
159 options: { allowedTools: ["Bash", "Glob"] }
160 })) {
161 if ("result" in message) console.log(message.result);
162 }
163 ```
164 </CodeGroup>
165 </Step>
166</Steps>
167
168**Pronto para construir?** Siga o [Guia de Início Rápido](/pt/agent-sdk/quickstart) para criar um agente que encontra e corrige bugs em minutos.
169 25
170<h2 id="capabilities">26<h2 id="capabilities">
171 Capacidades27 Capacidades
172</h2>28</h2>
173 29
174Tudo o que torna Claude Code poderoso está disponível no SDK:30Essas capacidades do Claude Code estão disponíveis no SDK:
175
176<Tabs>
177 <Tab title="Ferramentas integradas">
178 Seu agente pode ler arquivos, executar comandos e pesquisar bases de código imediatamente. As ferramentas principais incluem:
179
180 | Ferramenta | O que faz |
181 | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
182 | **Read** | Ler qualquer arquivo no diretório de trabalho |
183 | **Write** | Criar novos arquivos |
184 | **Edit** | Fazer edições precisas em arquivos existentes |
185 | **Bash** | Executar comandos de terminal, scripts, operações git |
186 | **Monitor** | Observar um script em segundo plano e reagir a cada linha de saída como um evento |
187 | **Glob** | Encontrar arquivos por padrão (`**/*.ts`, `src/**/*.py`) |
188 | **Grep** | Pesquisar conteúdo de arquivos com regex |
189 | **WebSearch** | Pesquisar na web por informações atuais |
190 | **WebFetch** | Buscar e analisar conteúdo de páginas da web |
191 | **[AskUserQuestion](/pt/agent-sdk/user-input#handle-clarifying-questions)** | Fazer perguntas de esclarecimento ao usuário com opções de múltipla escolha |
192
193 Este exemplo cria um agente que pesquisa sua base de código por comentários TODO:
194
195 <CodeGroup>
196 ```python Python theme={null}
197 import asyncio
198 from claude_agent_sdk import query, ClaudeAgentOptions
199
200
201 async def main():
202 async for message in query(
203 prompt="Find all TODO comments and create a summary",
204 options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]),
205 ):
206 if hasattr(message, "result"):
207 print(message.result)
208
209
210 asyncio.run(main())
211 ```
212
213 ```typescript TypeScript theme={null}
214 import { query } from "@anthropic-ai/claude-agent-sdk";
215
216 for await (const message of query({
217 prompt: "Find all TODO comments and create a summary",
218 options: { allowedTools: ["Read", "Glob", "Grep"] }
219 })) {
220 if ("result" in message) console.log(message.result);
221 }
222 ```
223 </CodeGroup>
224 </Tab>
225
226 <Tab title="hooks">
227 Execute código personalizado em pontos-chave do ciclo de vida do agente. Os hooks do SDK usam funções de retorno de chamada para validar, registrar, bloquear ou transformar o comportamento do agente.
228
229 **Hooks disponíveis:** `PreToolUse`, `PostToolUse`, `Stop`, `SessionStart`, `SessionEnd`, `UserPromptSubmit` e muito mais.
230
231 Este exemplo registra todas as alterações de arquivo em um arquivo de auditoria:
232
233 <CodeGroup>
234 ```python Python theme={null}
235 import asyncio
236 from datetime import datetime
237 from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher
238
239
240 async def log_file_change(input_data, tool_use_id, context):
241 file_path = input_data.get("tool_input", {}).get("file_path", "unknown")
242 with open("./audit.log", "a") as f:
243 f.write(f"{datetime.now()}: modified {file_path}\n")
244 return {}
245
246
247 async def main():
248 async for message in query(
249 prompt="Refactor utils.py to improve readability",
250 options=ClaudeAgentOptions(
251 permission_mode="acceptEdits",
252 hooks={
253 "PostToolUse": [
254 HookMatcher(matcher="Edit|Write", hooks=[log_file_change])
255 ]
256 },
257 ),
258 ):
259 if hasattr(message, "result"):
260 print(message.result)
261
262
263 asyncio.run(main())
264 ```
265
266 ```typescript TypeScript theme={null}
267 import { query, HookCallback } from "@anthropic-ai/claude-agent-sdk";
268 import { appendFile } from "fs/promises";
269
270 const logFileChange: HookCallback = async (input) => {
271 const filePath = (input as any).tool_input?.file_path ?? "unknown";
272 await appendFile("./audit.log", `${new Date().toISOString()}: modified ${filePath}\n`);
273 return {};
274 };
275
276 for await (const message of query({
277 prompt: "Refactor utils.py to improve readability",
278 options: {
279 permissionMode: "acceptEdits",
280 hooks: {
281 PostToolUse: [{ matcher: "Edit|Write", hooks: [logFileChange] }]
282 }
283 }
284 })) {
285 if ("result" in message) console.log(message.result);
286 }
287 ```
288 </CodeGroup>
289
290 [Saiba mais sobre hooks →](/pt/agent-sdk/hooks)
291 </Tab>
292
293 <Tab title="Subagentes">
294 Crie agentes especializados para lidar com subtarefas focadas. Seu agente principal delega trabalho e os subagentes relatam resultados.
295 31
296 Defina agentes personalizados com instruções especializadas. Os subagentes são invocados via a ferramenta Agent, então inclua `Agent` em `allowedTools` para aprovar automaticamente essas invocações:32| Capacidade | O que faz | Saiba mais |
33| -------------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
34| Ferramentas integradas | Ler, escrever, editar arquivos, executar comandos e pesquisar na web | [Referência de ferramentas](/docs/pt/tools-reference) |
35| Hooks | Executar código personalizado em pontos-chave do ciclo de vida do agente | [Hooks](/docs/pt/agent-sdk/hooks) |
36| Subagentes | Gerar agentes especializados para subtarefas focadas | [Subagentes](/docs/pt/agent-sdk/subagents) |
37| MCP | Conectar ferramentas externas e fontes de dados via o Model Context Protocol | [MCP](/docs/pt/agent-sdk/mcp) |
38| Permissões | Controlar quais ferramentas são executadas automaticamente, quais precisam de aprovação | [Permissões](/docs/pt/agent-sdk/permissions) |
39| Sessões | Manter contexto entre trocas, retomar ou bifurcar depois | [Sessões](/docs/pt/agent-sdk/sessions) |
40| Skills, comandos e memória | Carregar automaticamente do `.claude/` do seu projeto e de `~/.claude/`, igual ao Claude Code | [Skills](/docs/pt/agent-sdk/skills), [Comandos](/docs/pt/agent-sdk/skills#commands-in-agent-sdk-sessions), [Memória](/docs/pt/agent-sdk/modifying-system-prompts), [Carregamento de configuração](/docs/pt/agent-sdk/claude-code-features) |
41| Plugins | Empacotar skills, agentes, hooks e servidores MCP, e carregá-los por caminho local | [Plugins](/docs/pt/agent-sdk/plugins) |
297 42
298 <CodeGroup>43<h2 id="get-started">
299 ```python Python theme={null}44 Comece agora
300 import asyncio
301 from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition
302
303
304 async def main():
305 async for message in query(
306 prompt="Use the code-reviewer agent to review this codebase",
307 options=ClaudeAgentOptions(
308 allowed_tools=["Read", "Glob", "Grep", "Agent"],
309 agents={
310 "code-reviewer": AgentDefinition(
311 description="Expert code reviewer for quality and security reviews.",
312 prompt="Analyze code quality and suggest improvements.",
313 tools=["Read", "Glob", "Grep"],
314 )
315 },
316 ),
317 ):
318 if hasattr(message, "result"):
319 print(message.result)
320
321
322 asyncio.run(main())
323 ```
324
325 ```typescript TypeScript theme={null}
326 import { query } from "@anthropic-ai/claude-agent-sdk";
327
328 for await (const message of query({
329 prompt: "Use the code-reviewer agent to review this codebase",
330 options: {
331 allowedTools: ["Read", "Glob", "Grep", "Agent"],
332 agents: {
333 "code-reviewer": {
334 description: "Expert code reviewer for quality and security reviews.",
335 prompt: "Analyze code quality and suggest improvements.",
336 tools: ["Read", "Glob", "Grep"]
337 }
338 }
339 }
340 })) {
341 if ("result" in message) console.log(message.result);
342 }
343 ```
344 </CodeGroup>
345
346 As mensagens dentro do contexto de um subagente incluem um campo `parent_tool_use_id`, permitindo que você rastreie quais mensagens pertencem a qual execução de subagente.
347
348 [Saiba mais sobre subagentes →](/pt/agent-sdk/subagents)
349 </Tab>
350
351 <Tab title="MCP">
352 Conecte-se a sistemas externos via Model Context Protocol: bancos de dados, navegadores, APIs e [centenas mais](https://github.com/modelcontextprotocol/servers).
353
354 Este exemplo conecta o [servidor Playwright MCP](https://github.com/microsoft/playwright-mcp) para dar ao seu agente capacidades de automação de navegador:
355
356 <CodeGroup>
357 ```python Python theme={null}
358 import asyncio
359 from claude_agent_sdk import query, ClaudeAgentOptions
360
361
362 async def main():
363 async for message in query(
364 prompt="Open example.com and describe what you see",
365 options=ClaudeAgentOptions(
366 mcp_servers={
367 "playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]}
368 }
369 ),
370 ):
371 if hasattr(message, "result"):
372 print(message.result)
373
374
375 asyncio.run(main())
376 ```
377
378 ```typescript TypeScript theme={null}
379 import { query } from "@anthropic-ai/claude-agent-sdk";
380
381 for await (const message of query({
382 prompt: "Open example.com and describe what you see",
383 options: {
384 mcpServers: {
385 playwright: { command: "npx", args: ["@playwright/mcp@latest"] }
386 }
387 }
388 })) {
389 if ("result" in message) console.log(message.result);
390 }
391 ```
392 </CodeGroup>
393
394 [Saiba mais sobre MCP →](/pt/agent-sdk/mcp)
395 </Tab>
396
397 <Tab title="Permissões">
398 Controle exatamente quais ferramentas seu agente pode usar. Permita operações seguras, bloqueie operações perigosas ou exija aprovação para ações sensíveis.
399
400 <Note>
401 Para prompts de aprovação interativa e a ferramenta `AskUserQuestion`, consulte [Lidar com aprovações e entrada do usuário](/pt/agent-sdk/user-input).
402 </Note>
403
404 Este exemplo cria um agente somente leitura que pode analisar mas não modificar código. `allowed_tools` pré-aprova `Read`, `Glob` e `Grep`.
405
406 <CodeGroup>
407 ```python Python theme={null}
408 import asyncio
409 from claude_agent_sdk import query, ClaudeAgentOptions
410
411
412 async def main():
413 async for message in query(
414 prompt="Review this code for best practices",
415 options=ClaudeAgentOptions(
416 allowed_tools=["Read", "Glob", "Grep"],
417 ),
418 ):
419 if hasattr(message, "result"):
420 print(message.result)
421
422
423 asyncio.run(main())
424 ```
425
426 ```typescript TypeScript theme={null}
427 import { query } from "@anthropic-ai/claude-agent-sdk";
428
429 for await (const message of query({
430 prompt: "Review this code for best practices",
431 options: {
432 allowedTools: ["Read", "Glob", "Grep"]
433 }
434 })) {
435 if ("result" in message) console.log(message.result);
436 }
437 ```
438 </CodeGroup>
439
440 [Saiba mais sobre permissões →](/pt/agent-sdk/permissions)
441 </Tab>
442
443 <Tab title="Sessões">
444 Mantenha contexto em múltiplas trocas. Claude se lembra de arquivos lidos, análises feitas e histórico de conversa. Retome sessões depois ou divida-as para explorar diferentes abordagens.
445
446 Este exemplo captura o ID da sessão da primeira consulta, depois retoma para continuar com contexto completo:
447
448 <CodeGroup>
449 ```python Python theme={null}
450 import asyncio
451 from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage, ResultMessage
452
453
454 async def main():
455 session_id = None
456
457 # First query: capture the session ID
458 async for message in query(
459 prompt="Read the authentication module",
460 options=ClaudeAgentOptions(allowed_tools=["Read", "Glob"]),
461 ):
462 if isinstance(message, SystemMessage) and message.subtype == "init":
463 session_id = message.data["session_id"]
464
465 # Resume with full context from the first query
466 async for message in query(
467 prompt="Now find all places that call it", # "it" = auth module
468 options=ClaudeAgentOptions(resume=session_id),
469 ):
470 if isinstance(message, ResultMessage):
471 print(message.result)
472
473
474 asyncio.run(main())
475 ```
476
477 ```typescript TypeScript theme={null}
478 import { query } from "@anthropic-ai/claude-agent-sdk";
479
480 let sessionId: string | undefined;
481
482 // First query: capture the session ID
483 for await (const message of query({
484 prompt: "Read the authentication module",
485 options: { allowedTools: ["Read", "Glob"] }
486 })) {
487 if (message.type === "system" && message.subtype === "init") {
488 sessionId = message.session_id;
489 }
490 }
491
492 // Resume with full context from the first query
493 for await (const message of query({
494 prompt: "Now find all places that call it", // "it" = auth module
495 options: { resume: sessionId }
496 })) {
497 if ("result" in message) console.log(message.result);
498 }
499 ```
500 </CodeGroup>
501
502 [Saiba mais sobre sessões →](/pt/agent-sdk/sessions)
503 </Tab>
504</Tabs>
505
506<h3 id="claude-code-features">
507 Recursos do Claude Code
508</h3>
509
510O SDK também suporta a configuração baseada em sistema de arquivos do Claude Code. Com opções padrão, o SDK carrega estas do `.claude/` em seu diretório de trabalho e `~/.claude/`. Para restringir quais fontes carregam, defina `setting_sources` (Python) ou `settingSources` (TypeScript) em suas opções.
511
512| Recurso | Descrição | Localização |
513| ------------------------------------------------ | ---------------------------------------------------------------------------------------- | ---------------------------------- |
514| [Skills](/pt/agent-sdk/skills) | Capacidades especializadas que Claude usa automaticamente ou você invoca com `/name` | `.claude/skills/*/SKILL.md` |
515| [Commands](/pt/agent-sdk/slash-commands) | Comandos personalizados no formato legado. Use skills para novos comandos personalizados | `.claude/commands/*.md` |
516| [Memory](/pt/agent-sdk/modifying-system-prompts) | Contexto do projeto e instruções | `CLAUDE.md` ou `.claude/CLAUDE.md` |
517| [Plugins](/pt/agent-sdk/plugins) | Estenda com skills, agentes, hooks e servidores MCP | Programático via opção `plugins` |
518
519<h2 id="compare-the-agent-sdk-to-other-claude-tools">
520 Compare o Agent SDK com outras ferramentas Claude
521</h2>45</h2>
522 46
523A Plataforma Claude oferece múltiplas maneiras de construir com Claude. Aqui está como o Agent SDK se encaixa:47Siga o [Quickstart](/docs/pt/agent-sdk/quickstart) para instalar o SDK, definir sua chave de API e construir seu primeiro agente, um que encontra e corrige bugs em código existente.
524
525<Tabs>
526 <Tab title="Agent SDK vs Client SDK">
527 O [Anthropic Client SDK](https://platform.claude.com/docs/pt/api/client-sdks) oferece acesso direto à API: você envia prompts e implementa a execução de ferramentas você mesmo. O **Agent SDK** oferece Claude com execução de ferramentas integrada.
528
529 Com o Client SDK, você implementa um loop de ferramentas. Com o Agent SDK, Claude o manipula:
530
531 <CodeGroup>
532 ```python Python theme={null}
533 # Client SDK: You implement the tool loop
534 response = client.messages.create(...)
535 while response.stop_reason == "tool_use":
536 result = your_tool_executor(response.tool_use)
537 response = client.messages.create(tool_result=result, **params)
538
539 # Agent SDK: Claude handles tools autonomously
540 async for message in query(prompt="Fix the bug in auth.py"):
541 print(message)
542 ```
543
544 ```typescript TypeScript theme={null}
545 // Client SDK: You implement the tool loop
546 let response = await client.messages.create({ ...params });
547 while (response.stop_reason === "tool_use") {
548 const result = yourToolExecutor(response.tool_use);
549 response = await client.messages.create({ tool_result: result, ...params });
550 }
551 48
552 // Agent SDK: Claude handles tools autonomously49<Note>
553 for await (const message of query({ prompt: "Fix the bug in auth.ts" })) {50 A menos que previamente aprovado, a Anthropic não permite que desenvolvedores terceirizados ofereçam login claude.ai ou limites de taxa para seus produtos, incluindo agentes construídos no Claude Agent SDK. Use os métodos de autenticação de chave de API descritos no [Quickstart](/docs/pt/agent-sdk/quickstart) em vez disso.
554 console.log(message);51</Note>
555 }
556 ```
557 </CodeGroup>
558 </Tab>
559
560 <Tab title="Agent SDK vs Claude Code CLI">
561 Mesmas capacidades, interface diferente:
562
563 | Caso de uso | Melhor escolha |
564 | -------------------------- | -------------- |
565 | Desenvolvimento interativo | CLI |
566 | Pipelines CI/CD | SDK |
567 | Aplicações personalizadas | SDK |
568 | Tarefas únicas | CLI |
569 | Automação em produção | SDK |
570
571 Muitas equipes usam ambas: CLI para desenvolvimento diário, SDK para produção. Os fluxos de trabalho se traduzem diretamente entre eles.
572 </Tab>
573
574 <Tab title="Agent SDK vs Managed Agents">
575 [Managed Agents](https://platform.claude.com/docs/pt/managed-agents/overview) é uma API REST hospedada: a Anthropic executa o agente e a sandbox, e sua aplicação envia eventos e transmite resultados de volta. O **Agent SDK** é uma biblioteca que executa o loop do agente dentro de seu próprio processo.
576
577 | | Agent SDK | Managed Agents |
578 | ------------------------------ | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
579 | **Executa em** | Seu processo, sua infraestrutura | Infraestrutura gerenciada pela Anthropic |
580 | **Interface** | Biblioteca Python ou TypeScript | API REST |
581 | **O agente trabalha em** | Arquivos em sua infraestrutura | Uma sandbox gerenciada por sessão |
582 | **Estado da sessão** | JSONL em seu sistema de arquivos | Log de eventos hospedado pela Anthropic |
583 | **Ferramentas personalizadas** | Funções Python ou TypeScript em processo | Claude dispara a ferramenta; você executa e retorna resultados |
584 | **Melhor para** | Prototipagem local, agentes que trabalham diretamente em seu sistema de arquivos e serviços | Agentes de produção sem operar infraestrutura de sandbox ou sessão, sessões de longa duração e assíncronas |
585
586 Um caminho comum é fazer prototipagem com o Agent SDK localmente e depois migrar para Managed Agents para produção.
587 </Tab>
588</Tabs>
589 52
590<h2 id="changelog">53<h2 id="changelog">
591 Changelog54 Changelog
596* **TypeScript SDK**: [ver CHANGELOG.md](https://github.com/anthropics/claude-agent-sdk-typescript/blob/main/CHANGELOG.md)59* **TypeScript SDK**: [ver CHANGELOG.md](https://github.com/anthropics/claude-agent-sdk-typescript/blob/main/CHANGELOG.md)
597* **Python SDK**: [ver CHANGELOG.md](https://github.com/anthropics/claude-agent-sdk-python/blob/main/CHANGELOG.md)60* **Python SDK**: [ver CHANGELOG.md](https://github.com/anthropics/claude-agent-sdk-python/blob/main/CHANGELOG.md)
598 61
599<h2 id="reporting-bugs">62<h2 id="report-bugs">
600 Relatando bugs63 Relatando bugs
601</h2>64</h2>
602 65
613 76
614**Permitido:**77**Permitido:**
615 78
616* "Claude Agent" (preferido para menus suspensos)79* "Claude Agent", preferido para menus suspensos
617* "Claude" (quando dentro de um menu já rotulado "Agents")80* "Claude", quando dentro de um menu já rotulado "Agents"
618* "{YourAgentName} Powered by Claude" (se você tiver um nome de agente existente)81* "\{YourAgentName} Powered by Claude", se você tiver um nome de agente existente
619 82
620**Não permitido:**83**Não permitido:**
621 84
634 Próximos passos97 Próximos passos
635</h2>98</h2>
636 99
637<CardGroup cols={2}>100Estes recursos cobrem detalhes técnicos mais profundos e projetos de exemplo para construir com o Agent SDK.
638 <Card title="Guia de Início Rápido" icon="play" href="/pt/agent-sdk/quickstart">
639 Construa um agente que encontra e corrige bugs em minutos
640 </Card>
641
642 <Card title="Agentes de exemplo" icon="star" href="https://github.com/anthropics/claude-agent-sdk-demos">
643 Assistente de email, agente de pesquisa e muito mais
644 </Card>
645
646 <Card title="TypeScript SDK" icon="code" href="/pt/agent-sdk/typescript">
647 Referência completa da API TypeScript e exemplos
648 </Card>
649 101
650 <Card title="Python SDK" icon="code" href="/pt/agent-sdk/python">102* [Guia de Início Rápido](/docs/pt/agent-sdk/quickstart): construa seu primeiro agente que encontra e corrige bugs
651 Referência completa da API Python e exemplos103* [Guia de migração](/docs/pt/agent-sdk/migration-guide): migre dos pacotes Claude Code SDK para o Agent SDK
652 </Card>104* [Loop do agente](/docs/pt/agent-sdk/agent-loop): como Claude planeja, chama ferramentas e decide quando uma tarefa está concluída
653</CardGroup>105* [Agentes de exemplo](https://github.com/anthropics/claude-agent-sdk-demos): aplicativos de demonstração para desenvolvimento local
106* [TypeScript SDK](/docs/pt/agent-sdk/typescript): referência completa da API TypeScript e exemplos
107* [Python SDK](/docs/pt/agent-sdk/python): referência completa da API Python e exemplos
108* [Design do harness do agente](https://claude.com/blog/a-harness-for-every-task-dynamic-workflows-in-claude-code): como o time Claude Code usa fluxos de trabalho dinâmicos para orquestrar muitos subagentos simultaneamente
