Adicionar ferramentas ao agente de IA do Azure

As ferramentas são o que permitem que seu agente tome medidas: chamar APIs, executar código, pesquisar arquivos ou interagir com serviços externos. Sem ferramentas, um agente só pode gerar texto com base no que ele já sabe. Com as ferramentas, ele se torna capaz de agir sobre o mundo.

O Microsoft Agent Framework dá suporte a duas categorias amplas de ferramentas: ferramentas fornecidas pelo serviço que são hospedadas e gerenciadas pelo provedor e ferramentas de função personalizadas que você mesmo escreve e registra com o agente.

Ferramentas fornecidas pelo serviço

Ao usar o provedor Foundry, uma variedade de ferramentas hospedadas está disponível sem necessidade de implementação adicional. Você os habilita incluindo-os na configuração do agente — o provedor cuida da execução propriamente dita.

As ferramentas mais usadas pelo serviço incluem:

Ferramentas de função personalizadas

As ferramentas de função personalizada permitem estender o agente com qualquer lógica necessária: chamar APIs internas, consultar bancos de dados, executar cálculos ou qualquer outra coisa que uma função Python possa fazer.

Para registrar uma função como uma ferramenta, passe-a diretamente para o agente durante a criação. A estrutura inspeciona a assinatura da função e gera um esquema que informa ao modelo o que a função faz, quais parâmetros espera e o que ela retorna.

Para que o modelo chame uma ferramenta de forma confiável, sua função precisa ser claramente descrita. O Agent Framework dá suporte a duas abordagens:

• Anotações de tipo com descrições—use o tipo Annotated do Python com uma descrição de campo em cada parâmetro. O docstring da função serve como a descrição da ferramenta.
• O decorador @tool — especifique explicitamente o nome e a descrição da ferramenta nos argumentos do decorador, o que dá a você controle total sobre o que o modelo vê. Você também pode fornecer um esquema explícito usando um modelo Pydantic se precisar de controle preciso sobre a estrutura de entrada.

Em ambos os casos, a estrutura manipula automaticamente a geração de esquema e a invocação de ferramentas. Quando o modelo determina que uma ferramenta deve ser chamada, a estrutura executa a função e retorna o resultado para o modelo antes que a resposta final seja gerada.

Adicionando várias ferramentas

Você pode registrar várias ferramentas com um único agente. Passe uma lista de funções ao criar o agente e o modelo seleciona automaticamente a ferramenta mais apropriada para cada parte da conversa. Você não precisa escrever nenhuma lógica de roteamento– a estrutura manipula a orquestração de ferramentas com base no contexto da conversa e nas descrições da ferramenta que você fornece.

Aprovação da ferramenta

Para cenários em que as invocações de ferramentas devem exigir revisão humana antes da execução, o Agent Framework dá suporte a um padrão de aprovação de ferramenta . Quando o modo de aprovação é habilitado em uma ferramenta, o agente pausa antes de chamar essa função e solicita confirmação. Isso é útil para ações irreversíveis, caras ou que envolvem dados confidenciais. O comportamento de aprovação pode ser configurado para cada ferramenta usando o parâmetro approval_mode no decorador @tool.

Usando um agente como uma ferramenta

Os agentes podem ser compostos usando um agente como uma ferramenta para outro. Você converte um agente interno em uma ferramenta de função e passa-o para um agente externo, que pode delegar tarefas específicas a ele. Isso permite designs modulares em que agentes especializados lidam com domínios específicos e um agente coordenador roteia solicitações entre eles— um padrão explorado com mais profundidade no módulo de vários agentes.

Práticas recomendadas para ferramentas personalizadas

• Escreva descrições claras: a capacidade do modelo de escolher a ferramenta certa depende inteiramente das descrições fornecidas. Seja específico sobre o que a função faz e quando ela deve ser usada.
• Anotar todos os parâmetros – descrever cada entrada para que o modelo possa construir chamadas válidas, especialmente quando os nomes de parâmetro sozinhos não são autoexplicativos.
• Retornar dados significativos — as ferramentas devem retornar uma saída estruturada e interpretável. O modelo usa o valor retornado diretamente ao formar sua resposta.
• Manter as ferramentas focadas— cada ferramenta deve fazer uma coisa bem. Combinar várias responsabilidades em uma única função torna mais difícil para o modelo invocá-lo corretamente.
• Manipular erros normalmente — se uma ferramenta encontrar uma entrada inesperada ou um serviço externo falhar, retorne uma mensagem de erro informativa em vez de gerar uma exceção, para que o modelo possa responder com ajuda.