Использование инструментов для работы с функциями с агентом

На этом шаге руководства показано, как использовать инструменты функций с агентом, который работает на базе службы завершения чата Azure OpenAI.

Это важно

Не все типы агентов поддерживают средства функций. Некоторые могут поддерживать только пользовательские встроенные средства, не позволяя вызывающему предоставлять свои собственные функции. На этом шаге используется ChatClientAgent, который поддерживает инструменты функций.

Предпосылки

Предварительные требования и установка пакетов NuGet см. в разделе "Создание и запуск простого агента " в этом руководстве.

Создание агента с помощью средств функций

Средства функций — это просто пользовательский код, который нужно, чтобы агент мог вызывать при необходимости. Вы можете превратить любой метод C# в инструмент функции, используя AIFunctionFactory.Create метод для создания AIFunction экземпляра из метода.

Если вам нужно предоставить дополнительные описания функции или его параметров агенту, чтобы он был более точно выбирать между разными функциями, можно использовать System.ComponentModel.DescriptionAttribute атрибут в методе и его параметрах.

Вот пример простой функции, которая имитирует получение данных о погоде для указанного местоположения. Он снабжен атрибутами описания для предоставления дополнительных сведений о себе и его параметре расположения агенту.

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.";

При создании агента теперь можно предоставить агенту функциональное средство, передав список инструментов в метод CreateAIAgent.

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)]);

Теперь вы можете просто запустить агент как обычно, и агент сможет вызывать инструмент функции GetWeather при необходимости.

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

Это важно

Не все типы агентов поддерживают средства функций. Некоторые могут поддерживать только пользовательские встроенные средства, не позволяя вызывающему предоставлять свои собственные функции. На этом шаге используются агенты, созданные с помощью клиентов чата, которые поддерживают функциональные инструменты.

Предпосылки

Для предварительных требований и установки пакетов Python см. шаг Создание и запуск простого агента в этом учебном пособии.

Создание агента с помощью средств функций

Средства функций — это просто пользовательский код, который нужно, чтобы агент мог вызывать при необходимости. Вы можете превратить любую функцию Python в средство-функцию, передав его параметру агента tools при создании агента.

Если вам нужно указать дополнительные описания функции или её параметров агенту, чтобы он мог более точно выбирать между разными функциями, можно использовать аннотации типов Python с Annotated и возможности Pydantic Field для предоставления описаний.

Вот пример простой функции, которая имитирует получение данных о погоде для указанного местоположения. В нем используются аннотации типов для предоставления дополнительных описаний об функции и ее параметре "расположение" агенту.

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."

Вы также можете использовать ai_function декоратор для явного указания имени и описания функции:

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."

Если в декораторе не указаны параметры name и description, фреймворк автоматически будет использовать имя функции и docstring в качестве резервных вариантов.

При создании агента теперь можно предоставить ему функциональный инструмент, передав его в параметр tools.

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
)

Теперь вы можете просто запустить агент в обычном режиме, и агент сможет вызывать инструмент функции get_weather при необходимости.

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

asyncio.run(main())

Создание класса с несколькими инструментами функций

Вы также можете создать класс, содержащий несколько инструментов функций в качестве методов. Это может быть полезно для упорядочивания связанных функций или для передачи состояния между ними.

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."

При создании агента теперь можно указать все методы класса в качестве функций:

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

Функции также могут быть декорированы тем же ai_function декоратором, что и раньше.

Дальнейшие шаги

Использование инструментов функций с участием человека в процессе утверждений