Usando ferramentas funcionais com um agente

Esta etapa do tutorial mostra como usar ferramentas de função com um agente, onde o agente é criado no serviço de Conclusão de Chat do Azure OpenAI.

Importante

Nem todos os tipos de agentes suportam ferramentas de função. Alguns podem suportar apenas ferramentas internas personalizadas, sem permitir que o chamador forneça suas próprias funções. Esta etapa usa um ChatClientAgent, que realmente suporta ferramentas de função.

Pré-requisitos

Para obter pré-requisitos e instalar pacotes NuGet, consulte a etapa Criar e executar um agente simples neste tutorial.

Criar o agente com ferramentas funcionais

As ferramentas de função são apenas um código personalizado que você deseja que o agente possa chamar quando necessário. Você pode transformar qualquer método C# em uma ferramenta de função, usando o AIFunctionFactory.Create método para criar uma AIFunction instância a partir do método.

Se você precisar fornecer descrições adicionais sobre a função ou seus parâmetros para o agente, para que ele possa escolher com mais precisão entre diferentes funções, você pode usar o System.ComponentModel.DescriptionAttribute atributo no método e seus parâmetros.

Aqui está um exemplo de uma simples ferramenta de funções que finge obter o clima para um determinado local. Ele é decorado com atributos de descrição para fornecer descrições adicionais sobre si mesmo e seu parâmetro de localização para o agente.

using System.ComponentModel;

[Description("Get the weather for a given location.")]
static string GetWeather([Description("The location to get the weather for.")] string location)
    => $"The weather in {location} is cloudy with a high of 15°C.";

Ao criar o agente, agora você pode fornecer a ferramenta de função para o agente, passando uma lista de ferramentas para o CreateAIAgent método.

using System;
using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using OpenAI;

AIAgent agent = new AzureOpenAIClient(
    new Uri("https://<myresource>.openai.azure.com"),
    new AzureCliCredential())
     .GetChatClient("gpt-4o-mini")
     .CreateAIAgent(instructions: "You are a helpful assistant", tools: [AIFunctionFactory.Create(GetWeather)]);

Agora você pode simplesmente executar o agente como de costume, e o agente conseguirá chamar a função de ferramenta GetWeather quando necessário.

Console.WriteLine(await agent.RunAsync("What is the weather like in Amsterdam?"));

Importante

Nem todos os tipos de agentes suportam ferramentas de função. Alguns podem suportar apenas ferramentas internas personalizadas, sem permitir que o chamador forneça suas próprias funções. Esta etapa usa agentes criados através de clientes de chat, os quais suportam ferramentas funcionais.

Pré-requisitos

Para pré-requisitos e instalação de pacotes Python, consulte a etapa Criar e executar um agente simples neste tutorial.

Criar o agente com ferramentas funcionais

As ferramentas de função são apenas um código personalizado que você deseja que o agente possa chamar quando necessário. Você pode transformar qualquer função Python em uma funcionalidade de função passando-a para o parâmetro tools do agente ao criar o agente.

Se você precisar fornecer descrições adicionais sobre a função ou seus parâmetros para o agente, para que ele possa escolher com mais precisão entre diferentes funções, você pode usar as anotações de tipo do Python com Annotated e Pydantic Field para fornecer descrições.

Aqui está um exemplo de uma simples ferramenta de funções que finge obter o clima para um determinado local. Ele usa anotações de tipo para fornecer descrições adicionais sobre a função e seu parâmetro de localização para o agente.

from typing import Annotated
from pydantic import Field

def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
) -> str:
    """Get the weather for a given location."""
    return f"The weather in {location} is cloudy with a high of 15°C."

Você também pode usar o decorador ai_function para especificar explicitamente o nome e a descrição da função:

from typing import Annotated
from pydantic import Field
from agent_framework import ai_function

@ai_function(name="weather_tool", description="Retrieves weather information for any location")
def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
) -> str:
    return f"The weather in {location} is cloudy with a high of 15°C."

Se não especificar os parâmetros name e description no decorador ai_function, o framework usará automaticamente o nome da função e a docstring como fallbacks.

Ao criar o agente, agora você pode fornecer a ferramenta de função para o agente, passando-a para o tools parâmetro.

import asyncio
from agent_framework.azure import AzureOpenAIChatClient
from azure.identity import AzureCliCredential

agent = AzureOpenAIChatClient(credential=AzureCliCredential()).create_agent(
    instructions="You are a helpful assistant",
    tools=get_weather
)

Agora você pode simplesmente executar o agente normalmente, e o agente poderá chamar a ferramenta de get_weather função quando necessário.

async def main():
    result = await agent.run("What is the weather like in Amsterdam?")
    print(result.text)

asyncio.run(main())

Criar uma classe com várias ferramentas de função

Você também pode criar uma classe que contém várias ferramentas de função como métodos. Isto pode ser útil para organizar funções relacionadas ou quando se deseja passar o estado entre elas.

class WeatherTools:
    def __init__(self):
        self.last_location = None

    def get_weather(
        self,
        location: Annotated[str, Field(description="The location to get the weather for.")],
    ) -> str:
        """Get the weather for a given location."""
        return f"The weather in {location} is cloudy with a high of 15°C."

    def get_weather_details(self) -> int:
        """Get the detailed weather for the last requested location."""
        if self.last_location is None:
            return "No location specified yet."
        return f"The detailed weather in {self.last_location} is cloudy with a high of 15°C, low of 7°C, and 60% humidity."

Ao criar o agente, agora você pode fornecer todos os métodos da classe como funções:

tools = WeatherTools()
agent = AzureOpenAIChatClient(credential=AzureCliCredential()).create_agent(
    instructions="You are a helpful assistant",
    tools=[tools.get_weather, tools.get_weather_details]
)

Você também pode decorar as funções com o mesmo ai_function decorador de antes.

Próximos passos

Usando ferramentas de funções com aprovações com intervenção humana no processo