Usando ferramentas de funções com um agente

Pré-requisitos

Para pré-requisitos e instalação de 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 simplesmente códigos personalizados que você deseja que o agente possa chamar quando for 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ê poderá usar o System.ComponentModel.DescriptionAttribute atributo no método e seus parâmetros.

Aqui está um exemplo de uma ferramenta de função simples que falsifica a obtenção do 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 executar o agente como de costume, e o agente poderá chamar a ferramenta de função GetWeather quando necessário.

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

Pré-requisitos

Para pré-requisitos e instalação de pacotes do 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 simplesmente códigos personalizados que você deseja que o agente possa chamar quando for necessário. Você pode transformar qualquer função Python em uma ferramenta de funções 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ê poderá usar anotações de tipo do Python com Annotated e Pydantic Field para fornecer descrições.

Aqui está um exemplo de uma ferramenta de função simples que falsifica a obtenção do 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 ai_function decorador 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 você não especificar os parâmetros name e description no decorador ai_function, o framework usará automaticamente o nome e o docstring da função como padrões de substituição.

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 ele poderá chamar a ferramenta de função get_weather 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. Isso pode ser útil para organizar funções relacionadas em conjunto ou quando você 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.