Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Pesquisa de Ferramentas: Ferramentas Dinâmicas

Aula 10 de 25 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Pesquisa de Ferramentas: Ferramentas Dinâmicas
  2. O Problema do Excesso de Ferramentas
  3. Ativar a Pesquisa de Ferramentas
  4. Padrão: Seleção Manual de Ferramentas
  5. Padrão: Ferramentas Dinâmicas Conscientes do Contexto
  6. Otimizar as Descrições das Ferramentas
  7. Pontos-chave

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