Adicionar ferramentas ao agente de IA do Azure

As ferramentas são o que permite ao seu agente agir — chamar APIs, executar código, pesquisar ficheiros ou interagir com serviços externos. Sem ferramentas, um agente só pode gerar texto com base no que já sabe. Com ferramentas, torna-se capaz de agir sobre o mundo.

O Microsoft Agent Framework suporta duas grandes categorias de ferramentas: ferramentas fornecidas por serviços que são alojadas e geridas pelo fornecedor, e ferramentas de funções personalizadas que escreve por si próprio e regista junto do agente.

Ferramentas fornecidas pelo serviço

Ao utilizar o fornecedor Foundry, está disponível uma variedade de ferramentas alojadas sem qualquer implementação adicional. Ativa-os incluindo-os na configuração do agente — o prestador trata da execução propriamente dita.

As ferramentas mais utilizadas disponibilizadas pelo serviço incluem:

Ferramentas de função personalizadas

Ferramentas de funções personalizadas permitem-te estender o teu agente com qualquer lógica que precises—chamando APIs internas, consultando bases de dados, fazendo cálculos ou qualquer outra coisa que uma função Python possa fazer.

Para registar uma função como ferramenta, passa-a diretamente ao agente durante a criação. O framework inspeciona a assinatura da função e gera um esquema que indica ao modelo o que a função faz, que parâmetros espera e o que devolve.

Para o modelo chamar uma ferramenta de forma fiável, a sua função precisa de ser claramente descrita. O Agent Framework suporta duas abordagens:

• Anotações de tipo com descrições—utilize o tipo Annotated do Python com uma descrição do campo em cada parâmetro. O docstring da função serve como descrição da ferramenta.
• O @tool decorador — especifica explicitamente o nome e a descrição da ferramenta como argumentos do decorador, dando-te total controlo sobre o que o modelo vê. Também pode fornecer um esquema explícito usando um modelo Pydantic se precisar de controlo preciso sobre a estrutura de entrada.

Em qualquer dos casos, o framework gere automaticamente a geração de esquemas e a invocação da ferramenta. Quando o modelo determina que deve ser chamada uma ferramenta, o framework executa a função e devolve o resultado ao modelo antes de ser gerada a resposta final.

Adição de múltiplas ferramentas

Pode registar várias ferramentas num único agente. Passe uma lista de funções ao criar o agente, e o modelo seleciona automaticamente a ferramenta mais adequada para cada parte da conversa. Não precisas de escrever lógica de roteamento — o framework trata da orquestração das ferramentas com base no contexto da conversa e nas descrições das ferramentas que forneces.

Aprovação de ferramentas

Para cenários em que as invocações de ferramentas devem exigir revisão humana antes da execução, o Agent Framework suporta um padrão de aprovação de ferramentas . Quando o modo de aprovação está ativado numa ferramenta, o agente faz uma pausa antes de chamar essa função e solicita confirmação. Isto é útil para ações que são irreversíveis, dispendiosas ou que envolvem dados sensíveis. O comportamento de aprovação pode ser configurado para cada ferramenta através do parâmetro approval_mode no decorador @tool.

Usar um agente como ferramenta

Os agentes podem ser compostos usando um agente como ferramenta para outro. Converte um agente interno numa ferramenta funcional e passa-o a um agente externo, que pode depois delegar-lhe tarefas específicas. Isto permite designs modulares onde agentes especializados tratam de domínios específicos e um agente coordenador encaminha pedidos entre eles — um padrão explorado com mais profundidade no módulo multi-agente.

Boas práticas para ferramentas personalizadas

• Escreva descrições claras — a capacidade do modelo de escolher a ferramenta certa depende inteiramente das descrições que fornece. Seja específico sobre o que a função faz e quando deve ser usada.
• Anote cada parâmetro — descreva cada entrada para que o modelo possa construir chamadas válidas, especialmente quando os nomes dos parâmetros sozinhos não são autoexplicativos.
• Devolva dados significativos — as ferramentas devem devolver resultados estruturados e interpretáveis. O modelo utiliza o valor de retorno diretamente ao formar a sua resposta.
• Mantém as ferramentas focadas — cada ferramenta deve fazer uma coisa bem. Combinar múltiplas responsabilidades numa única função torna mais difícil para o modelo invocá-las corretamente.
• Trate os erros de forma elegante — se uma ferramenta encontrar uma entrada inesperada ou um serviço externo falhar, devolve uma mensagem de erro informativa em vez de abrir uma exceção, para que o modelo possa responder de forma útil.