SpyBara
Go Premium

agent-sdk/custom-tools.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 84 additions and 74 deletions.

2026
Wed 9 22:58 Sat 12 03:02 Fri 18 23:58

Dê a Claude ferramentas personalizadas

Defina ferramentas personalizadas com o servidor MCP em processo do Agent SDK do Claude para que Claude possa chamar suas funções, acessar suas APIs e executar operações específicas do domínio.

Ferramentas personalizadas estendem o Agent SDK permitindo que você defina suas próprias funções que Claude pode chamar durante uma conversa. Usando o servidor MCP em processo do SDK, você pode dar a Claude acesso a bancos de dados, APIs externas, lógica específica do domínio ou qualquer outra capacidade que sua aplicação necessite.

Referência rápida

Se você quer... Faça isto
Definir uma ferramenta Use @tool (Python) ou tool() (TypeScript) com um nome, descrição, esquema e manipulador. Veja Criar uma ferramenta personalizada.
Registrar uma ferramenta com Claude Envolva em create_sdk_mcp_server / createSdkMcpServer e passe para mcpServers em query(). Veja Chamar uma ferramenta personalizada.
Pré-aprovar uma ferramenta Adicione às suas ferramentas permitidas. Veja Configurar ferramentas permitidas.
Remover uma ferramenta integrada do contexto de Claude Passe um array tools listando apenas os integrados que você quer. Veja Configurar ferramentas permitidas.
Deixar Claude chamar ferramentas em paralelo Defina readOnlyHint: true em ferramentas sem efeitos colaterais. Veja Adicionar anotações de ferramentas.
Controlar a mensagem de erro que Claude lê Retorne isError: true para compor a mensagem em vez de expor a exceção bruta. Veja Tratar erros.
Retornar imagens ou arquivos Use blocos image ou resource no array de conteúdo. Veja Retornar imagens e recursos.
Retornar um resultado JSON legível por máquina Defina structuredContent no resultado. Veja Retornar dados estruturados.
Escalar para muitas ferramentas Use tool search para carregar ferramentas sob demanda.

Criar uma ferramenta personalizada

Uma ferramenta é definida por quatro partes, passadas como argumentos para o auxiliar tool() em TypeScript ou o decorador @tool em Python:

  • Nome: um identificador único que Claude usa para chamar a ferramenta.
  • Descrição: o que a ferramenta faz. Claude lê isso para decidir quando chamá-la.
  • Esquema de entrada: os argumentos que Claude deve fornecer. Em TypeScript, isso é sempre um esquema Zod, e os args do manipulador são digitados automaticamente a partir dele. Em Python, isso é um dicionário mapeando nomes para tipos, como {"latitude": float}, que o SDK converte para JSON Schema para você. O decorador Python também aceita um dicionário completo de JSON Schema diretamente quando você precisa de enums, intervalos, campos opcionais ou objetos aninhados.
  • Manipulador: a função assíncrona que é executada quando Claude chama a ferramenta. Ela recebe os argumentos validados e deve retornar um objeto com:
    • content (obrigatório): um array de blocos de resultado, cada um com um type de "text", "image", "audio", "resource" ou "resource_link". Veja Retornar imagens e recursos para blocos não-texto.
    • structuredContent (opcional): um objeto JSON contendo o resultado como dados legíveis por máquina, retornado junto com content. Veja Retornar dados estruturados.
    • isError (opcional): defina como true para sinalizar uma falha da ferramenta para que Claude possa reagir a ela. Veja Tratar erros.

Após definir uma ferramenta, envolva-a em um servidor com createSdkMcpServer (TypeScript) ou create_sdk_mcp_server (Python). O servidor é executado no processo dentro de sua aplicação, não como um processo separado.

Exemplo de ferramenta de clima

Este exemplo define uma ferramenta get_temperature e a envolve em um servidor MCP. Ele apenas configura a ferramenta; para passá-la para query e executá-la, veja Chamar uma ferramenta personalizada abaixo.

from typing import Any
import httpx
from claude_agent_sdk import tool, create_sdk_mcp_server


# Define a tool: name, description, input schema, handler
@tool(
"get_temperature",
"Get the current temperature at a location",
{"latitude": float, "longitude": float},
)
async def get_temperature(args: dict[str, Any]) -> dict[str, Any]:
async with httpx.AsyncClient() as client:
response = await client.get(
"https://api.open-meteo.com/v1/forecast",
params={
"latitude": args["latitude"],
"longitude": args["longitude"],
"current": "temperature_2m",
"temperature_unit": "fahrenheit",
},
)
data = response.json()

# Return a content array - Claude sees this as the tool result
return {
"content": [
{
"type": "text",
"text": f"Temperature: {data['current']['temperature_2m']}°F",
}
]
}


# Wrap the tool in an in-process MCP server
weather_server = create_sdk_mcp_server(
name="weather",
version="1.0.0",
tools=[get_temperature],
)

Veja a referência TypeScript tool() ou a referência Python @tool para detalhes completos dos parâmetros, incluindo formatos de entrada JSON Schema e estrutura de valor de retorno.

Chamar uma ferramenta personalizada

Passe o servidor MCP que você criou para query via a opção mcpServers. A chave em mcpServers se torna o segmento {server_name} no nome totalmente qualificado de cada ferramenta: mcp__{server_name}__{tool_name}. Liste esse nome em allowedTools para que a ferramenta seja executada sem um prompt de permissão.

Estes trechos reutilizam o weatherServer do exemplo acima para perguntar a Claude qual é o clima em um local específico.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def main():
options = ClaudeAgentOptions(
mcp_servers={"weather": weather_server},
allowed_tools=["mcp__weather__get_temperature"],
)

async for message in query(
prompt="What's the temperature in San Francisco?",
options=options,
):
# ResultMessage is the final message after all tool calls complete
if isinstance(message, ResultMessage) and message.subtype == "success":
print(message.result)


asyncio.run(main())

Combine este trecho com as definições de ferramenta e servidor do exemplo de ferramenta de clima em um arquivo, depois execute-o com python weather.py para Python ou npx tsx weather.ts para TypeScript. Claude chama get_temperature e o script imprime uma resposta de uma linha com a temperatura atual em San Francisco.

Adicionar mais ferramentas

Um servidor contém quantas ferramentas você listar em seu array tools. Com mais de uma ferramenta em um servidor, você pode listar cada uma em allowedTools individualmente ou usar o curinga mcp__weather__* para cobrir todas as ferramentas que o servidor expõe.

O exemplo abaixo define uma segunda ferramenta, get_precipitation_chance, e substitui a definição de weatherServer do exemplo de ferramenta de clima por uma que lista ambas as ferramentas no array.

# Define a second tool for the same server
@tool(
"get_precipitation_chance",
"Get the hourly precipitation probability for a location. "
"Optionally pass 'hours' (1-24) to control how many hours to return.",
{"latitude": float, "longitude": float},
)
async def get_precipitation_chance(args: dict[str, Any]) -> dict[str, Any]:
# 'hours' isn't in the schema - read it with .get() to make it optional
hours = args.get("hours", 12)
async with httpx.AsyncClient() as client:
response = await client.get(
"https://api.open-meteo.com/v1/forecast",
params={
"latitude": args["latitude"],
"longitude": args["longitude"],
"hourly": "precipitation_probability",
"forecast_days": 1,
},
)
data = response.json()
chances = data["hourly"]["precipitation_probability"][:hours]

return {
"content": [
{
"type": "text",
"text": f"Next {hours} hours: {'%, '.join(map(str, chances))}%",
}
]
}


# Rebuild the server with both tools in the array
weather_server = create_sdk_mcp_server(
name="weather",
version="1.0.0",
tools=[get_temperature, get_precipitation_chance],
)

Tool search está ativado por padrão e adia ferramentas SDK MCP: Claude vê o nome de cada ferramenta em uma lista compacta e carrega seu esquema completo sob demanda. Com a busca de ferramentas desativada, cada ferramenta neste array consome espaço da janela de contexto a cada turno. Em TypeScript, passe alwaysLoad: true no argumento extras de tool() ou nas opções de createSdkMcpServer() para manter o esquema completo de uma ferramenta no prompt inicial.

Adicionar anotações de ferramenta

Anotações de ferramenta são metadados opcionais descrevendo como uma ferramenta se comporta. Passe-as como o quinto argumento para o auxiliar tool() em TypeScript ou via o argumento de palavra-chave annotations para o decorador @tool em Python. Todos os campos de dica são Booleanos.

Campo Padrão Significado
readOnlyHint false A ferramenta não modifica seu ambiente. Controla se a ferramenta pode ser chamada em paralelo com outras ferramentas somente leitura.
destructiveHint true A ferramenta pode realizar atualizações destrutivas. Apenas informativo.
idempotentHint false Chamadas repetidas com os mesmos argumentos não têm efeito adicional. Apenas informativo.
openWorldHint true A ferramenta alcança sistemas fora de seu processo. Apenas informativo.

Anotações são metadados, não imposição. Uma ferramenta marcada com readOnlyHint: true ainda pode escrever em disco se isso for o que o manipulador faz. Mantenha a anotação precisa em relação ao manipulador.

Este exemplo adiciona readOnlyHint à ferramenta get_temperature do exemplo de ferramenta de clima.

from claude_agent_sdk import tool, ToolAnnotations


@tool(
"get_temperature",
"Get the current temperature at a location",
{"latitude": float, "longitude": float},
annotations=ToolAnnotations(
readOnlyHint=True
),  # Lets Claude batch this with other read-only calls
)
async def get_temperature(args):
return {"content": [{"type": "text", "text": "..."}]}

Veja ToolAnnotations na referência TypeScript ou Python.

Controlar o acesso à ferramenta

O exemplo de ferramenta de clima registrou um servidor e listou ferramentas em allowedTools. Esta seção aborda como definir o escopo de acesso quando você tem múltiplas ferramentas ou deseja restringir as ferramentas integradas. Para saber como os nomes das ferramentas são construídos, consulte Chamar uma ferramenta personalizada.

Configurar ferramentas permitidas

A opção tools e as listas de permitidas/não permitidas afetam duas camadas: disponibilidade, que controla se uma ferramenta aparece no contexto do Claude, e permissão, que controla se uma chamada é aprovada uma vez que Claude tenta usá-la. tools e entradas disallowedTools com nome simples alteram a disponibilidade. allowedTools e regras disallowedTools com escopo alteram a permissão. Se você nomear uma das ferramentas de rastreamento de tarefas em allowedTools, Claude Code também ativa a sessão.

Opção Camada Efeito
tools: ["Read", "Grep"] Disponibilidade Apenas as ferramentas integradas listadas estão no contexto do Claude. As ferramentas integradas não listadas são removidas. As ferramentas MCP não são afetadas.
tools: [] Disponibilidade Todas as ferramentas integradas são removidas. Claude pode usar apenas suas ferramentas MCP.
ferramentas permitidas Permissão As ferramentas listadas são executadas sem um prompt de permissão. Outras ferramentas não listadas permanecem disponíveis; as chamadas passam pelo fluxo de permissão.
ferramentas não permitidas Ambas Um nome de ferramenta simples como "Bash" remove a ferramenta do contexto do Claude, o mesmo que omiti-la de tools. Uma regra com escopo como "Bash(rm *)" deixa a ferramenta no contexto e nega apenas as chamadas correspondentes.

Para remover uma ferramenta integrada completamente, omita-a de tools ou liste seu nome simples em disallowedTools (Python: disallowed_tools); ambas mantêm a ferramenta fora do contexto para que Claude nunca tente usá-la. Uma regra disallowedTools com escopo bloqueia as chamadas correspondentes, mas deixa a ferramenta visível, então Claude pode desperdiçar um turno tentando usá-la. Consulte Configurar permissões para a ordem de avaliação completa.

Tratar erros

Um erro de handler não interrompe o loop do agente. O servidor MCP em processo do SDK captura exceções não capturadas e as retorna como resultados de erro, portanto, a forma como você relata um erro determina o que Claude lê, não se a consulta falha:

O que acontece Resultado
Handler lança uma exceção não capturada O servidor MCP a converte em um resultado de erro contendo a mensagem de exceção bruta. Claude vê essa mensagem e o loop do agente continua.
Handler captura o erro e retorna isError: true (TS) / "is_error": True (Python) Claude vê a mensagem que você compõe. Você pode adicionar contexto que a exceção bruta não possui, como qual solicitação falhou ou o que tentar em vez disso.

Em ambos os casos, Claude pode tentar novamente, tentar uma ferramenta diferente ou explicar a falha. Capture erros você mesmo quando a mensagem de exceção bruta não for suficiente para Claude agir.

O exemplo abaixo captura dois tipos de falhas dentro do handler e compõe a mensagem de erro que Claude lê. Um status HTTP diferente de 200 é capturado da resposta e retornado como um resultado de erro. Um erro de rede ou JSON inválido é capturado pelo try/except (Python) ou try/catch (TypeScript) circundante e também retornado como um resultado de erro. Em ambos os casos, Claude recebe uma mensagem que descreve a falha em vez de uma string de exceção bruta.

import json
import httpx
from typing import Any
from claude_agent_sdk import tool


@tool(
"fetch_data",
"Fetch data from an API",
{"endpoint": str},  # Simple schema
)
async def fetch_data(args: dict[str, Any]) -> dict[str, Any]:
try:
async with httpx.AsyncClient() as client:
response = await client.get(args["endpoint"])
if response.status_code != 200:
# Return the failure as a tool result so Claude can react to it.
# is_error marks this as a failed call rather than odd-looking data.
return {
"content": [
{
"type": "text",
"text": f"API error: {response.status_code} {response.reason_phrase}",
}
],
"is_error": True,
}

data = response.json()
return {"content": [{"type": "text", "text": json.dumps(data, indent=2)}]}
except Exception as e:
# Composes the message Claude reads. An uncaught exception would
# reach Claude as the raw str(e) with no context.
return {
"content": [{"type": "text", "text": f"Failed to fetch data: {str(e)}"}],
"is_error": True,
}

Retornar imagens e recursos

O array content em um resultado de ferramenta aceita blocos text, image, audio, resource e resource_link. Você pode misturá-los na mesma resposta. Em TypeScript, o SDK salva blocos de áudio em disco e Claude recebe um bloco de texto com o caminho do arquivo salvo; em Python, o SDK remove blocos de áudio do resultado da ferramenta e registra um aviso.

Claude recebe cada bloco de link de recurso como um bloco de texto contendo o nome, URI e descrição do link. Em TypeScript, sua aplicação também recebe os links como resourceLinks no tool_use_result da mensagem do usuário; em Python, o SDK os achata para texto antes que a CLI veja o resultado, portanto a chave resourceLinks do Python nunca é produzida para ferramentas em processo.

Imagens

Um bloco de imagem carrega os bytes da imagem inline, codificados em base64. Não há campo de URL. Para retornar uma imagem que existe em uma URL, busque-a no manipulador, leia os bytes da resposta e codifique-os em base64 antes de retornar. O resultado é processado como entrada visual.

Campo Tipo Notas
type "image"
data string Bytes codificados em base64. Apenas base64 bruto, sem prefixo data:image/...;base64,
mimeType string Obrigatório. Por exemplo image/png, image/jpeg, image/webp, image/gif 
import base64
import httpx
from claude_agent_sdk import tool


# Define a tool that fetches an image from a URL and returns it to Claude
@tool("fetch_image", "Fetch an image from a URL and return it to Claude", {"url": str})
async def fetch_image(args):
async with httpx.AsyncClient() as client:  # Fetch the image bytes
response = await client.get(args["url"])

return {
"content": [
{
"type": "image",
"data": base64.b64encode(response.content).decode(
"ascii"
),  # Base64-encode the raw bytes
"mimeType": response.headers.get(
"content-type", "image/png"
),  # Read MIME type from the response
}
]
}

Recursos

Um bloco de recurso incorpora um pedaço de conteúdo identificado por uma URI. A URI é um rótulo para Claude referenciar; o conteúdo real fica no campo text ou blob do bloco. Use isso quando sua ferramenta produz algo que faz sentido ser endereçado por nome depois, como um arquivo gerado ou um registro de um sistema externo.

Campo Tipo Notas
type "resource"
resource.uri string Identificador para o conteúdo. Qualquer esquema de URI
resource.text string O conteúdo, se for texto. Forneça este ou blob, não ambos
resource.blob string O conteúdo codificado em base64, se for binário. Apenas TypeScript: o SDK do Python remove recursos binários do resultado da ferramenta e registra um aviso
resource.mimeType string Opcional

Este exemplo mostra um bloco de recurso retornado de dentro de um manipulador de ferramenta. A URI file:///tmp/report.md é um rótulo que Claude pode referenciar depois; o SDK não lê desse caminho.

return {
content: [
{
type: "resource",
resource: {
uri: "file:///tmp/report.md", // Label for Claude to reference, not a path the SDK reads
mimeType: "text/markdown",
text: "# Report\n..." // The actual content, inline
}
}
]
};

Essas formas de bloco vêm do tipo MCP CallToolResult. Consulte a especificação MCP para a definição completa.

Retornar dados estruturados

structuredContent é um objeto JSON opcional no resultado, separado do array content. Use-o para retornar valores brutos que Claude possa ler como campos exatos em vez de analisá-los de uma string de texto ou imagem.

Quando structuredContent é definido, Claude recebe o JSON mais qualquer bloco de imagem ou recurso de content. Blocos de texto em content não são encaminhados, pois presume-se que duplicam os dados estruturados. O exemplo abaixo renderiza um gráfico como um bloco de imagem e retorna os pontos de dados por trás dele em structuredContent do mesmo manipulador. No trecho, chartPngBuffer é um Buffer contendo os bytes PNG renderizados.

return {
  content: [
    {
      type: "image",
      data: chartPngBuffer.toString("base64"),
      mimeType: "image/png"
    }
  ],
  structuredContent: {
    series: "temperature_2m",
    unit: "fahrenheit",
    points: [62.1, 63.4, 65.0, 64.2]
  }
};

Exemplo: conversor de unidades

Esta ferramenta converte valores entre unidades de comprimento, temperatura e peso. Um usuário pode perguntar "converter 100 quilômetros para milhas" ou "quanto é 72°F em Celsius", e Claude escolhe o tipo de unidade correto e as unidades da solicitação.

Demonstra dois padrões:

  • Esquemas Enum: unit_type é restrito a um conjunto fixo de valores. Em TypeScript, use z.enum(). Em Python, o esquema dict não suporta enums, portanto o dict de JSON Schema completo é necessário.
  • Tratamento de entrada não suportada: quando um par de conversão não é encontrado, o manipulador retorna isError: true para que Claude possa informar ao usuário o que deu errado em vez de tratar uma falha como um resultado normal.
from typing import Any
from claude_agent_sdk import tool, create_sdk_mcp_server


# z.enum() em TypeScript se torna uma restrição "enum" em JSON Schema.
# O esquema dict não tem equivalente, portanto JSON Schema completo é necessário.
@tool(
"convert_units",
"Convert a value from one unit to another",
{
"type": "object",
"properties": {
"unit_type": {
"type": "string",
"enum": ["length", "temperature", "weight"],
"description": "Category of unit",
},
"from_unit": {
"type": "string",
"description": "Unit to convert from, e.g. kilometers, fahrenheit, pounds",
},
"to_unit": {"type": "string", "description": "Unit to convert to"},
"value": {"type": "number", "description": "Value to convert"},
},
"required": ["unit_type", "from_unit", "to_unit", "value"],
},
)
async def convert_units(args: dict[str, Any]) -> dict[str, Any]:
conversions = {
"length": {
"kilometers_to_miles": lambda v: v * 0.621371,
"miles_to_kilometers": lambda v: v * 1.60934,
"meters_to_feet": lambda v: v * 3.28084,
"feet_to_meters": lambda v: v * 0.3048,
},
"temperature": {
"celsius_to_fahrenheit": lambda v: (v * 9) / 5 + 32,
"fahrenheit_to_celsius": lambda v: (v - 32) * 5 / 9,
"celsius_to_kelvin": lambda v: v + 273.15,
"kelvin_to_celsius": lambda v: v - 273.15,
},
"weight": {
"kilograms_to_pounds": lambda v: v * 2.20462,
"pounds_to_kilograms": lambda v: v * 0.453592,
"grams_to_ounces": lambda v: v * 0.035274,
"ounces_to_grams": lambda v: v * 28.3495,
},
}

key = f"{args['from_unit']}_to_{args['to_unit']}"
fn = conversions.get(args["unit_type"], {}).get(key)

if not fn:
return {
"content": [
{
"type": "text",
"text": f"Unsupported conversion: {args['from_unit']} to {args['to_unit']}",
}
],
"is_error": True,
}

result = fn(args["value"])
return {
"content": [
{
"type": "text",
"text": f"{args['value']} {args['from_unit']} = {result:.4f} {args['to_unit']}",
}
]
}


converter_server = create_sdk_mcp_server(
name="converter",
version="1.0.0",
tools=[convert_units],
)

Depois que o servidor é definido, passe-o para query da mesma forma que o exemplo de clima. Este exemplo envia três prompts diferentes em um loop para mostrar a mesma ferramenta tratando diferentes tipos de unidades. Para cada resposta, ele inspeciona objetos AssistantMessage (que contêm as chamadas de ferramenta que Claude fez durante esse turno) e imprime cada ToolUseBlock antes de imprimir o texto final ResultMessage. Isso permite que você veja quando Claude está usando a ferramenta versus respondendo a partir de seu próprio conhecimento.

Como tool search está ativado por padrão, a saída também pode incluir uma chamada ToolSearch conforme Claude carrega o esquema de ferramenta adiado.

import asyncio
from claude_agent_sdk import (
query,
ClaudeAgentOptions,
ResultMessage,
AssistantMessage,
ToolUseBlock,
)


async def main():
options = ClaudeAgentOptions(
mcp_servers={"converter": converter_server},
allowed_tools=["mcp__converter__convert_units"],
)

prompts = [
"Convert 100 kilometers to miles.",
"What is 72°F in Celsius?",
"How many pounds is 5 kilograms?",
]

for prompt in prompts:
try:
async for message in query(prompt=prompt, options=options):
if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, ToolUseBlock):
print(f"[tool call] {block.name}({block.input})")
elif isinstance(message, ResultMessage) and message.subtype == "success":
print(f"Q: {prompt}\nA: {message.result}\n")
except Exception as error:
# A single-shot query() raises after yielding an error result. Only success
# results are printed above, so handle the failure here and continue with
# the next prompt.
print(f"Call failed: {error}")


asyncio.run(main())

Próximos passos

Você pode misturar os padrões nesta página no mesmo servidor: um único servidor pode conter uma ferramenta de banco de dados, uma ferramenta de gateway de API e um renderizador de imagem lado a lado.

A partir daqui:

  • Se seu servidor crescer para dezenas de ferramentas, consulte pesquisa de ferramentas para adiar o carregamento delas até que Claude precise delas.
  • Para conectar a servidores MCP externos (sistema de arquivos, GitHub, Slack) em vez de construir os seus próprios, consulte Conectar servidores MCP.
  • Para controlar quais ferramentas são executadas automaticamente versus exigindo aprovação, consulte Configurar permissões.