Uso de Ferramentas e Chamada de Funções
O uso de ferramentas permite que LLMs solicitem a execução de funções em vez de adivinharem respostas. Defina ferramentas com esquemas, valide argumentos, execute com segurança e retorne resultados ao modelo.
Receita
tools = [{"type": "function", "function": {
"name": "get_order",
"parameters": {"type": "object", "properties": {"order_id": {"type": "string"}}, "required": ["order_id"]},
}}]
response = client.chat.completions.create(model="gpt-4o-mini", messages=messages, tools=tools)Exemplo de Trabalho
"""tool_use.py - loop de execução segura de ferramentas."""
from __future__ import annotations
import json
from pydantic import BaseModel, ValidationError
from openai import OpenAI
client = OpenAI()
class GetOrderArgs(BaseModel):
order_id: str
def get_order(order_id: str) -> dict:
orders = {"ORD-123": {"status": "shipped", "total": 49.99}}
return orders.get(order_id, {"error": "not found"})
TOOL_REGISTRY = {"get_order": (GetOrderArgs, get_order)}
tools = [{"type": "function", "function": {
"name": "get_order",
"description": "Pesquisar pedido por ID",
"parameters": GetOrderArgs.model_json_schema(),
}}]
messages = [{"role": "user", "content": "Qual é o status do pedido ORD-123?"}]
for _ in range(5):
resp = client.chat.completions.create(model="gpt-4o-mini", messages=messages, tools=tools)
msg = resp.choices[0].message
if not msg.tool_calls:
print(msg.content)
break
messages.append(msg)
for call in msg.tool_calls:
name = call.function.name
schema_cls, fn = TOOL_REGISTRY[name]
try:
args = schema_cls.model_validate_json(call.function.arguments)
result = fn(**args.model_dump())
except ValidationError as e:
result = {"error": str(e)}
messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(result)})Armadilhas
- Execução de argumentos não validados - Injeção de SQL via parâmetros de ferramenta. Correção: Validação Pydantic; consultas parametrizadas.
- Ferramentas com poder excessivo - o modelo pode excluir dados. Correção: ferramentas somente leitura; aprovação humana para escritas.
- Sem limite de iteração - loop infinito de ferramentas. Correção: máximo de 5-10 iterações.
Alternativas
| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| Chamada de ferramentas OpenAI | Modelos GPT | Claude (use o formato de ferramenta Anthropic) |
| LangChain @tool | Agentes LangGraph | Preferência por SDK bruto |
| MCP | Servidores de ferramentas padronizados | Ferramentas simples de aplicativo único |
FAQs
Ferramentas OpenAI vs Anthropic?
OpenAI: ferramentas em chat.completions. Anthropic: parâmetro tools com blocos tool_result.Quantas ferramentas?
5-10 ferramentas focadas superam 50 vagas.Descrições de ferramentas importam?
Sim - descrições claras melhoram a precisão da seleção.Chamadas de ferramentas paralelas?
Execute todas as tool_calls em uma resposta; retorne todos os resultados.Como testar ferramentas?
Teste unitário de cada função de ferramenta; teste de integração do loop com LLM mockado.Ferramentas perigosas?
Sandbox de execução de código; exija aprovação humana para escritas.Ferramenta não chamada?
Melhore a descrição; adicione exemplos no prompt do sistema.Ferramenta errada selecionada?
Refine as descrições das ferramentas; reduza a contagem de ferramentas.Argumentos de ferramenta estruturados?
Modelo Pydantic como esquema JSON para validação.Como registrar chamadas de ferramentas?
Registre o nome da ferramenta, argumentos, resultado e latência para observabilidade.Limitar taxa de APIs de ferramentas?
Semáforo em chamadas de API externas que as ferramentas fazem.MCP vs ferramentas inline?
MCP para ferramentas compartilhadas entre aplicativos; inline para específicas do aplicativo.Relacionados
- LangGraph e Loops de Agente
- SDK Anthropic Claude
- Saída Estruturada
- Protocolo de Contexto do Modelo (MCP)
- Avaliação e Guardrails
Versões do Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.