Conteúdo do curso Lição 230 de 250 · Projeto: Agente de Pesquisa que Usa Ferramentas
Projeto: Agente de Pesquisa que Usa Ferramentas

Registro de Ferramentas + Despachante

Todo "AI agent" sobre o qual você já leu termina em um componente sem glamour: um tool registry. O modelo emite algo como {"tool": "search", "args": {"query": "weather"}}, e your code tem que encontrar a função Python correta, verificar se os argumentos são sensatos, executá-la e devolver o resultado. Se errar essa camada, o agente inteiro está a um argumento malformado de um erro em produção. Esta primeira lição do projeto constrói exatamente essa camada, e você vai reutilizar a ideia em cada lição depois dela.

Você está construindo o despachante para um agente de pesquisa. Ele precisa de duas ferramentas para começar: uma search(query) que busca um fato, e uma calc(op, a, b) que faz aritmética. O registro mapeia um tool name para um par: a function, e um argument schema (o conjunto de nomes de argumentos que a tool aceita). Dispatch é o portão por onde tudo passa.

class Registry:
    def __init__(self):
        self.tools = {}   # name -> {"fn": callable, "args": set_of_arg_names}

    def register(self, name, fn, args):
        self.tools[name] = {"fn": fn, "args": set(args)}

    def dispatch(self, name, args):
        # 1. unknown tool name      -> raise KeyError
        # 2. args keys != schema    -> raise ValueError (missing OR extra)
        # 3. otherwise              -> call fn(**args) and return the result
        ...

As regras de despacho devem impor (este é o objetivo principal do exercício):

  • An unknown tool nome -> raise KeyError. O agente pediu algo que não existe.
  • As chaves do args dict devem corresponder ao schema registrado exatamente. Um argumento faltante ou um extra -> raise ValueError. É isso que impede uma {"q": ...} (chave errada) de não fazer nada silenciosamente.
  • A chamada válida -> execute fn(**args) e retorne o que ele retornar.

Por que um set para o schema? Porque a validação passa a ser apenas igualdade de conjunto: set(args) == self.tools[name]["args"]. Se isso for falso, descubra se as chaves estão faltando ou sobrando e lance ValueError de qualquer forma. Chamar com fn(**args) espalha o dictionary em keyword arguments, então a assinatura da function faz a vinculação final.

O gerente de contratação

A lendo "construiu um agente que usa ferramentas" está realmente perguntando: você lidou com o caminho infeliz? O agente que vai para produção é aquele cujo dispatcher recusa chamadas ruins com clareza em vez de corromper uma execução. Pressione Run para registrar duas ferramentas e observe as chamadas boas terem sucesso enquanto as ruins geram erro.

Sua vez

Construa uma classe Registry. register(name, fn, args) armazena a function e o esquema de nomes de argumentos (use um set). dispatch(name, args) deve: lançar KeyError para um nome de ferramenta desconhecido; lançar ValueError se as chaves de args não corresponderem exatamente ao esquema (faltando OU extras); caso contrário, chamar fn(**args) e retornar o resultado. Registre uma ferramenta search(query) e uma calc(op, a, b) para que o dispatcher tenha algo real para rotear.

Viu um problema nesta lição? Reporte-o · Pergunte sobre esta lição

Este exercício abre em breve

Termine a lição anterior para que esta seja desbloqueada. O curso inteiro é gratuito, não precisa de conta, e você pode ler esta lição agora mesmo.