Pesquisa de Ferramentas: Ferramentas Dinâmicas
Nesta página
Pesquisa de Ferramentas: Ferramentas Dinâmicas
Um agente de demonstração funciona perfeitamente com três ou quatro ferramentas. Um agente empresarial, no entanto, acumula inevitavelmente dezenas, por vezes centenas: faturação, recursos humanos, CRM, documentos, agendamento. A essa escala, enviar o catálogo completo ao modelo em cada pedido torna-se ineficiente e dispendioso em termos de tokens. A Pesquisa de Ferramentas resolve este problema selecionando dinamicamente as ferramentas relevantes para cada pedido.
O Problema do Excesso de Ferramentas
Imagine um agente com 50 ferramentas. Em cada chamada à API, os esquemas das 50 ferramentas são enviados no prompt. Isto consome milhares de tokens e pode confundir o modelo: quanto mais longa a lista, mais semelhantes se tornam as descrições e mais o modelo hesita entre ferramentas vizinhas. Os custos aumentam enquanto a precisão diminui — a pior combinação possível.
# Problema: demasiadas ferramentas
agent = Agent(
name="Super Agent",
instructions="You can do anything.",
tools=[tool_1, tool_2, tool_3, ... , tool_50], # 50 tools = lots of tokens
)
Ativar a Pesquisa de Ferramentas
A Pesquisa de Ferramentas utiliza um índice semântico para selecionar as ferramentas relevantes com base no pedido. Declara as suas ferramentas como habitualmente, mas o parâmetro tool_use_behavior="auto" permite ao modelo escolher no catálogo em vez de carregar tudo antecipadamente. No exemplo abaixo, um pedido para enviar um lembrete de pagamento não acionará ferramentas de RH, e vice-versa.
from agents import Agent, Runner, function_tool
# Definir muitas ferramentas
@function_tool
def create_invoice(client: str, amount: float) -> str:
"""Creates an invoice for a client."""
return f"Invoice created for {client}: €{amount}"
@function_tool
def send_reminder(invoice_id: str) -> str:
"""Sends a payment reminder for an unpaid invoice."""
return f"Reminder sent for invoice {invoice_id}"
@function_tool
def generate_hr_report(month: str) -> str:
"""Generates a human resources report for a given month."""
return f"HR report generated for {month}"
@function_tool
def schedule_interview(candidate: str, date: str) -> str:
"""Schedules a job interview with a candidate."""
return f"Interview scheduled with {candidate} on {date}"
# Muitas outras ferramentas...
agent = Agent(
name="Enterprise Agent",
instructions="You manage company operations.",
tools=[
create_invoice,
send_reminder,
generate_hr_report,
schedule_interview,
# ... 50 other tools
],
tool_use_behavior="auto", # O modelo seleciona dinamicamente
)
Padrão: Seleção Manual de Ferramentas
Se desejar controlo total sobre a seleção de ferramentas, implemente a sua própria lógica. O princípio é simples: um pequeno agente router lê o pedido e indica apenas o domínio relevante. De seguida, constrói o agente especializado em tempo real com apenas as ferramentas desse domínio. Uma frase como «enviar um lembrete para a fatura F-2026-114» sai do router com a resposta accounting, e o agente de execução nunca vê as ferramentas de RH.
from agents import Agent, Runner, function_tool
# Agrupar ferramentas por domínio
accounting_tools = [create_invoice, send_reminder]
hr_tools = [generate_hr_report, schedule_interview]
# Um agente router que seleciona o domínio
router = Agent(
name="Router",
instructions="""Determine the domain of the request.
Respond only with 'accounting' or 'hr'.""",
model="gpt-5.6-terra", # Rápido e barato para roteamento
output_type=str,
)
async def handle_request(message: str):
# Passo 1: Determinar o domínio
route = await Runner.run(router, message)
domain = route.final_output.strip().lower()
# Passo 2: Criar o agente especializado com as ferramentas corretas
if domain == "accounting":
tools = accounting_tools
instructions = "You manage the company's accounting."
elif domain == "hr":
tools = hr_tools
instructions = "You manage human resources."
else:
tools = accounting_tools + hr_tools
instructions = "You manage company operations."
specialized_agent = Agent(
name=f"{domain.capitalize()} Agent",
instructions=instructions,
tools=tools,
model="gpt-5.6-terra",
)
result = await Runner.run(specialized_agent, message)
return result.final_output
Utilizar o gpt-5.6-terra tanto para o roteamento como para a execução pertence à geração anterior de modelos; o raciocínio por trás do padrão permanece idêntico com a família GPT-5.6, onde as definições de esforço distinguem o router rápido do executor.
Padrão: Ferramentas Dinâmicas Conscientes do Contexto
A seleção não depende apenas da pergunta colocada; depende também de quem pergunta. Pode adaptar as ferramentas disponíveis com base no utilizador autenticado, matando dois coelhos de uma cajadada: menos tokens enviados e, mais importante, controlos de acesso aplicados antes mesmo de o modelo raciocinar. Um funcionário comercial obtém ferramentas de orçamentação, mas delete_account simplesmente não existe no seu agente.
from dataclasses import dataclass
@dataclass
class UserContext:
role: str # "admin", "manager", "employee"
department: str
def get_tools_for_role(ctx: UserContext) -> list:
"""Returns authorized tools based on role."""
base_tools = [search_document, view_schedule]
if ctx.role in ("admin", "manager"):
base_tools.extend([create_invoice, generate_hr_report])
if ctx.role == "admin":
base_tools.extend([modify_permissions, delete_account])
if ctx.department == "sales":
base_tools.extend([search_client, create_quote])
return base_tools
async def create_agent_for_user(ctx: UserContext):
tools = get_tools_for_role(ctx)
return Agent(
name="Custom Agent",
instructions=f"You assist a {ctx.role} in the {ctx.department} department.",
tools=tools,
model="gpt-5.6-terra",
)
Otimizar as Descrições das Ferramentas
Seja qual for o mecanismo de seleção escolhido, este baseia-se num único material: o texto das suas descrições. A qualidade destas descrições impacta diretamente a relevância da seleção. Compare as duas declarações abaixo: a primeira nada diz sobre o cenário de utilização, enquanto a segunda nomeia as entradas, a saída e quando utilizá-la.
# Mau: descrição vaga
@function_tool
def process_data(data: str) -> str:
"""Processes data."""
return "OK"
# Bom: descrição precisa e contextualizada
@function_tool
def calculate_gross_margin(revenue: float, production_cost: float) -> str:
"""Calculates gross margin as a percentage from revenue
and production cost. Useful for quarterly financial analysis."""
margin = ((revenue - production_cost) / revenue) * 100
return f"Gross margin: {margin:.1f}% (Revenue: €{revenue}, Costs: €{production_cost})"
Uma boa descrição de ferramenta é como uma boa docstring: explica quando utilizar a ferramenta, não apenas o que ela faz. Dedique dez minutos a rever as descrições do seu agente, questionando-se para cada uma delas se um colega conseguiria escolher a ferramenta correta lendo apenas essa frase. É exatamente esse o exercício que o modelo realiza.
Pontos-chave
- A Pesquisa de Ferramentas seleciona dinamicamente as ferramentas relevantes para cada pedido
- Com muitas ferramentas, um agente router pode determinar o domínio antecipadamente
- Adapte as ferramentas disponíveis com base na função e no contexto do utilizador
- A qualidade da descrição da ferramenta impacta a precisão da seleção
- Utilize um modelo leve para um roteamento rápido e um modelo capaz para a execução