O que Construindo Aplicações com Claude faz?
Esta skill ajuda você a construir aplicações com Claude. Escolha a superfície certa com base nas suas necessidades, detecte a linguagem do projeto e, em seguida, leia a documentação específica da linguagem.
Antes de Começar
Examine o arquivo de destino (ou, se não houver arquivo de destino, o prompt e o projeto) em busca de marcadores de provedor não-Anthropic — import openai, from openai, langchain_openai, OpenAI(, gpt-4, gpt-5, nomes de arquivo como agent-openai.py ou *-generic.py, ou qualquer instrução explícita para manter o código neutro em relação ao provedor. Se encontrar algum, pare e informe ao usuário que esta skill produz código do SDK do Claude/Anthropic; pergunte se ele deseja alterar o arquivo para o Claude ou prefere uma implementação que não seja do Claude. Não edite um arquivo não-Anthropic com chamadas do SDK da Anthropic.
Requisito de Saída
Quando o usuário pedir para adicionar, modificar ou implementar um recurso do Claude, seu código deve chamar o Claude através de uma das seguintes opções:
- O SDK oficial da Anthropic para a linguagem do projeto (
anthropic,@anthropic-ai/sdk,com.anthropic.*, etc.). Esta é a opção padrão sempre que existir um SDK compatível para o projeto. - HTTP puro (
curl,requests,fetch,httpx, etc.) — apenas quando o usuário pedir explicitamente por cURL/REST/HTTP puro, o projeto for um projeto shell/cURL, ou a linguagem não tiver SDK oficial.
Nunca misture os dois — não use requests/fetch em um projeto Python ou TypeScript apenas porque parece mais leve. Nunca recorra a adaptadores compatíveis com OpenAI.
Nunca adivinhe o uso do SDK. Nomes de funções, nomes de classes, namespaces, assinaturas de métodos e caminhos de importação devem vir de documentação explícita — seja dos arquivos {lang}/ nesta skill ou dos repositórios oficiais do SDK ou links de documentação listados em shared/live-sources.md. Se a ligação necessária não estiver explicitamente documentada nos arquivos da skill, faça WebFetch do repositório relevante do SDK a partir de shared/live-sources.md antes de escrever código. Não deduza APIs Ruby/Java/Go/PHP/C# a partir de formas cURL ou do SDK de outra linguagem.
Se o WebFetch ou o acesso ao repositório falhar (restrição de rede, tempo limite, bloqueio de clonagem): não continue tentando — escreva o código a partir dos padrões e tabelas de namespace/package no arquivo {lang}/, execute o compilador ou interpretador e itere com base na saída de erro. Para SDKs com tipagem estática (C#, Java, Go), um loop de compilação e correção com base em erros locais chega ao código funcional mais rápido do que pesquisa de rede bloqueada.
Padrões
A menos que o usuário solicite o contrário:
Para a versão do modelo Claude, use Claude Opus 5, que pode ser acessado através da string exata do modelo claude-opus-5. Por favor, use pensamento adaptativo (thinking: {type: "adaptive"}) para qualquer coisa remotamente complicada. E, finalmente, use streaming para qualquer requisição que possa envolver entrada longa, saída longa ou max_tokens alto — isso evita atingir timeouts de requisição. Use o auxiliar .get_final_message() / .finalMessage() do SDK para obter a resposta completa se não precisar lidar com eventos de stream individuais
⚠️ Derivação de API — Seu Conhecimento de Treinamento Pode Estar Desatualizado
Várias formas comuns da API do Claude mudaram em 2025–2026. Se você se lembrar de um padrão do treinamento, verifique-o nos arquivos {lang}/ desta skill antes de escrever — as linhas abaixo são os pontos de derivação mais frequentes:
| Área | Conhecimento desatualizado | API Atual |
|---|---|---|
| Pensamento estendido | thinking: {type: "enabled", budget_tokens: N} | Em modelos Claude 4.6+: thinking: {type: "adaptive"}. budget_tokens está obsoleto no Opus 4.6 / Sonnet 4.6 e rejeitado com 400 no Fable 5 / Sonnet 5 / Opus 5 / 4.8 / 4.7. Modelos anteriores a 4.6 ainda usam budget_tokens. |
| Tipo de ferramenta de busca web / fetch web | web_search_20250305, web_fetch_20250910 | web_search_20260209, web_fetch_20260209 (filtragem dinâmica) no Opus 5/4.8/4.7/4.6, Sonnet 5 e Sonnet 4.6. Modelos mais antigos mantêm as variantes básicas; no Vertex AI, apenas a web_search_20250305 básica está disponível (web fetch não está no Vertex) — veja o QR de Server Tools abaixo. |
| Nomes de parâmetros PHP | nomes snake_case como argumentos nomeados (max_tokens) | Argumentos nomeados de nível superior são camelCase (maxTokens). As chaves de array aninhadas variam por recurso (ex.: 'taskBudget', 'skillID', 'mcp_server_name') — copie a chave exata do exemplo documentado; não converta em massa. |
| Credenciais de Agentes Gerenciados | Manter secrets do lado do servidor via ferramentas personalizadas (a única opção antes do lançamento dos cofres) | Credenciais Vault environment_variable — armazenadas pela Anthropic, substituídas na saída, nunca visíveis no sandbox (shared/managed-agents-tools.md → Vaults). Ferramentas personalizadas do lado do servidor continuam sendo a alternativa para sandboxes auto-hospedados. |
Os arquivos {lang}/ nesta skill são a referência autoritativa sobre os padrões lembrados.
Subcomandos
Se a Solicitação do Usuário no final deste prompt for uma string de subcomando simples (sem prosa), pesquise todas as tabelas de Subcomandos neste documento — incluindo quaisquer uma em seções anexadas abaixo — e siga a Ação correspondente diretamente. Isso permite que os usuários invoquem fluxos específicos via /claude-api <subcomando>. Se nenhuma tabela no documento corresponder, trate a solicitação como prosa normal.
| Subcomando | Ação |
|---|---|
migrate | Migrar código existente da API Claude para um modelo mais novo. Leia shared/model-migration.md imediatamente e siga em ordem: Passo 0 (confirme o escopo — pergunte quais arquivos/diretórios antes de qualquer edição), Passo 1 (classifique cada arquivo), depois a seção de alterações de quebra por destino. Não resuma o guia — execute-o. Se o usuário não nomeou um modelo de destino, pergunte para qual modelo migrar na mesma rodada da pergunta de escopo. |
Detecção de Linguagem
Antes de ler exemplos de código, determine em qual linguagem o usuário está trabalhando:
-
Examine os arquivos do projeto para inferir a linguagem:
*.py,requirements.txt,pyproject.toml,setup.py,Pipfile→ Python — leia depython/*.ts,*.tsx,package.json,tsconfig.json→ TypeScript — leia detypescript/*.js,*.jsx(sem arquivos.tspresentes) → TypeScript — JS usa o mesmo SDK, leia detypescript/*.java,pom.xml,build.gradle→ Java — leia dejava/*.kt,*.kts,build.gradle.kts→ Java — Kotlin usa o SDK Java, leia dejava/*.scala,build.sbt→ Java — Scala usa o SDK Java, leia dejava/*.go,go.mod→ Go — leia dego/*.rb,Gemfile→ Ruby — leia deruby/*.cs,*.csproj→ C# — leia decsharp/*.php,composer.json→ PHP — leia dephp/
-
Se múltiplas linguagens forem detectadas (ex.: arquivos Python e TypeScript):
- Verifique a qual linguagem o arquivo ou pergunta atual do usuário se refere
- Se ainda ambíguo, pergunte: "Detectei arquivos Python e TypeScript. Qual linguagem você está usando para a integração com a API Claude?"
-
Se a linguagem não puder ser inferida (projeto vazio, sem arquivos fonte ou linguagem não suportada):
- Use AskUserQuestion com opções: Python, TypeScript, Java, Go, Ruby, cURL/HTTP puro, C#, PHP
- Se AskUserQuestion não estiver disponível, use exemplos Python por padrão e observe: "Mostrando exemplos Python. Avise-me se precisar de uma linguagem diferente."
-
Se uma linguagem não suportada for detectada (Rust, Swift, C++, Elixir, etc.):
- Sugira exemplos cURL/HTTP puro de
curl/e observe que SDKs da comunidade podem existir - Ofereça-se para mostrar exemplos Python ou TypeScript como implementações de referência
- Sugira exemplos cURL/HTTP puro de
-
Se o usuário precisar de exemplos cURL/HTTP puro, leia de
curl/.
Suporte a Recursos Específicos por Linguagem
Todas as linguagens SDK acima suportam tanto o Tool Runner beta quanto os Agentes Gerenciados (beta) — Python (decorador @beta_tool), TypeScript (betaZodTool + Zod), Java (classes anotadas), Go (BetaToolRunner no pacote toolrunner), Ruby (BaseTool + tool_runner), C# (BetaToolRunner + esquema JSON puro), PHP (BetaRunnableTool + toolRunner()); os pontos de entrada de código estão na referência rápida de Padrões de Uso de Ferramentas abaixo. cURL é HTTP puro (sem recursos SDK) e suporta Agentes Gerenciados.
Exemplos de código de Agentes Gerenciados: veja o guia de leitura na seção
## Agentes Gerenciados (Beta)abaixo.
Qual Superfície Devo Usar?
Comece simples. Use o nível mais simples que atenda às suas necessidades. Chamadas únicas de API e workflows lidam com a maioria dos casos de uso — recorrer a agentes apenas quando a tarefa genuinamente exigir exploração aberta e orientada por modelo. "Mais simples" significa a menor quantidade de código que você possui: para um agente hospedado, agendado ou com memória, Agentes Gerenciados geralmente é a opção mais simples (sem código de loop, sem arquivos de estado, sem agendador), mesmo sendo uma plataforma maior.
| Caso de Uso | Nível | Superfície Recomendada | Por quê? |
|---|---|---|---|
| Classificação, sumarização, extração, Q&A | Chamada única de LLM | API Claude | Uma requisição, uma resposta |
| Processamento em lote ou embeddings | Chamada única de LLM | API Claude | Endpoints especializados |
| Pipelines multi-etapas com lógica controlada por código | Workflow | API Claude + uso de ferramentas | Você orquestra o loop |
| Agente personalizado com suas próprias ferramentas | Agente | API Claude + uso de ferramentas | Máxima flexibilidade |
| Agente stateful gerenciado pelo servidor com workspace | Agente | Agentes Gerenciados | A Anthropic executa o loop e hospeda o sandbox de execução de ferramentas |
| Configurações de agente persistidas e versionadas | Agente | Agentes Gerenciados | Agentes são objetos armazenados; sessões fixam uma versão |
| Agente multi-turn de longa duração com montagens de arquivo | Agente | Agentes Gerenciados | Contêineres por sessão, fluxo de eventos SSE, Skills + MCP |
| Agente que executa em um agendamento (cron, "toda noite") | Agente | Agentes Gerenciados — implantações agendadas | As implantações disparam sessões autonomamente; sem agendador do lado do cliente |
Nota: Agentes Gerenciados é a escolha certa quando você quer que a Anthropic execute o loop do agente e hospede o contêiner onde as ferramentas executam — operações de arquivo, bash, execução de código são executadas no workspace por sessão. Se você quiser hospedar o compute você mesmo ou executar seu próprio runtime de ferramentas personalizadas, API Claude + uso de ferramentas é a escolha certa — use o tool runner para o loop agentic — seus hooks por turno ainda fornecem portões de aprovação, logging, interceptação de erros e execução condicional (veja
shared/tool-use-concepts.md) — ou o loop manual quando você quiser possuir todo o loop você mesmo.
Acesso ao provedor de nuvem. Claude Platform on AWS é operado pela Anthropic com paridade de API no mesmo dia — veja
shared/claude-platform-on-aws.mdpara configuração do cliente. Para disponibilidade por recurso em Claude Platform on AWS, Amazon Bedrock, Google Vertex AI e Microsoft Foundry, vejashared/platform-availability.md— essa tabela é a fonte única da verdade nesta skill; não deduza disponibilidade de outro lugar.
Construindo um Agente: Quatro Abordagens
Depois de decidir que você realmente precisa de um agente (uso de ferramentas aberto e orientado por modelo), existem quatro maneiras distintas de construir um. Duas perguntas independentes as separam: quem fornece o harness (o loop do agente + gerenciamento de contexto) e quem fornece a implantação (a infraestrutura na qual o agente é executado). O Tool Runner e o Claude Agent SDK fornecem apenas um harness — você ainda os hospeda e implanta — e é por isso que são fáceis de confundir. Agentes Gerenciados (CMA) é a única opção que fornece ambos o harness e a implantação gerenciada; o loop manual não fornece nenhum.
| # | Abordagem | Você escreve | Harness e implantação | Ferramentas disponíveis | Use quando |
|---|---|---|---|---|---|
| 1 | API Claude — loop manual | O loop while stop_reason == "tool_use" você mesmo | Você constrói o harness; você hospeda | Apenas ferramentas que você define | Você quer possuir o loop inteiro — sem dependência beta, ou um fluxo de controle que os hooks por turno do Tool Runner não atendem |
| 2 | API Claude — Tool Runner (client.beta.messages.tool_runner + @beta_tool / betaZodTool) | Apenas as funções de ferramenta | O SDK fornece o loop (apenas harness); você hospeda | Apenas ferramentas que você define | Um agente de ferramentas personalizadas sem escrever o loop manualmente (a maioria dos casos). Os hooks por turno ainda fornecem portões de aprovação, interceptação de erros, modificação de resultado (ex.: cache_control), repetições, streaming e compactação |
| 3 | Agentes Gerenciados (REST, beta) | Configuração do agente + resultados de suas ferramentas | A Anthropic fornece o harness e hospeda um sandbox por sessão (harness + implantação) | Sandbox hospedado pela Anthropic (bash, arquivos, execução de código) + Skills/MCP + suas ferramentas | Você quer que a Anthropic execute o loop e hospede o workspace por sessão; configurações persistidas/versionadas; sessões de longa duração |
| 4 | Claude Agent SDK — produto separado (claude-agent-sdk / @anthropic-ai/claude-agent-sdk) | Um prompt + opções | O SDK fornece o harness do Claude Code + ferramentas integradas (apenas harness); você hospeda | Ferramentas integradas Read/Write/Edit/Bash/Glob/Grep/WebSearch/WebFetch + MCP + subagentes | Você quer um agente de codificação/sistema de arquivos completo executando em sua própria infraestrutura |
A divisão harness/implantação é o modelo mental principal: as opções 1, 2 e 4 deixam a implantação com você; apenas a opção 3 (CMA) adiciona implantação gerenciada. As opções 1–3 são o que esta skill gera; a opção 4 é uma biblioteca diferente com seus próprios documentos — veja a desambiguação abaixo.
Tool Runner ≠ Claude Agent SDK. Eles soam parecidos, mas são pacotes diferentes:
- Tool Runner faz parte do SDK regular da API Anthropic (
anthropic/@anthropic-ai/sdk), acessado viaclient.beta.messages.tool_runner. Ele automatiza...