Typy agentów programu Microsoft Agent Framework

Proste agenty oparte na usługach wnioskowania

Struktura agentów ułatwia tworzenie prostych agentów na podstawie wielu różnych usług wnioskowania. Każda usługa wnioskowania zapewniająca implementację Microsoft.Extensions.AI.IChatClient może służyć do kompilowania tych agentów. Microsoft.Agents.AI.ChatClientAgent to klasa agenta używana do dostarczania agenta dla dowolnej implementacji IChatClient.

Te programy wspierają szeroką gamę funkcji dostępnych od razu:

1. Wywoływanie funkcji
2. Konwersacje wielowątkowe z zarządzaniem lokalną historią czatu lub zarządzanie historią czatu jako usługa
3. Narzędzia dostarczane przez dostosowaną usługę (np. MCP, wykonywanie kodu)
4. Strukturalne dane wyjściowe

Aby utworzyć jednego z tych agentów, po prostu skonstruuj ChatClientAgent używając wybranej implementacji IChatClient.

using Microsoft.Agents.AI;

var agent = new ChatClientAgent(chatClient, instructions: "You are a helpful assistant");

Aby ułatwić tworzenie tych agentów dla wielu popularnych usług, mamy także asystentów. Aby uzyskać więcej informacji, zobacz dokumentację dla każdej usługi:

Złożeni agenci niestandardowi

Istnieje również możliwość utworzenia w pełni niestandardowych agentów, które nie są tylko obudowami wokół elementu IChatClient. Struktura agentów udostępnia typ podstawowy AIAgent. Ten typ podstawowy jest główną abstrakcją dla wszystkich agentów, która, gdy jest podklasowana, umożliwia pełną kontrolę nad zachowaniem i możliwościami agenta.

Aby uzyskać więcej informacji, zobacz dokumentację dotyczącą agentów niestandardowych .

Proxy dla agentów zdalnych

Struktura agenta udostępnia gotowe AIAgent implementacje dla typowych protokołów agentów hostowanych przez usługę, takich jak A2A. Dzięki temu można łatwo nawiązać połączenie z agentami zdalnymi i korzystać z nich z poziomu aplikacji.

Aby uzyskać więcej informacji, zobacz dokumentację dla każdego typu agenta:

Dokumentacja opcji zestawu SDK platformy Azure i interfejsu OpenAI

W przypadku korzystania z usług Azure AI Foundry, Azure OpenAI lub OpenAI masz różne opcje zestawu SDK do łączenia się z tymi usługami. W niektórych przypadkach istnieje możliwość użycia wielu zestawów SDK do łączenia się z tą samą usługą lub używania tego samego zestawu SDK do łączenia się z różnymi usługami. Poniżej znajduje się lista różnych opcji dostępnych za pomocą adresu URL, którego należy użyć podczas nawiązywania połączenia z poszczególnymi. Pamiętaj, aby zastąpić <resource> i <project> rzeczywistymi nazwami zasobów i projektów.

1. Aktualizacja z Azure OpenAI do Azure AI Foundry
2. Zalecamy korzystanie z zestawu OpenAI SDK.
3. Chociaż zalecamy używanie zestawu OpenAI SDK do uzyskiwania dostępu do modeli usługi Azure AI Foundry, modele usługi Azure AI Foundry obsługują modele od wielu różnych dostawców, a nie tylko openAI. Wszystkie te modele są obsługiwane za pośrednictwem zestawu OpenAI SDK.

Korzystanie z zestawu OpenAI SDK

Jak pokazano w powyższej tabeli, pakiet SDK OpenAI może służyć do łączenia się z wieloma usługami. W zależności od usługi, z którą nawiązujesz połączenie, może być konieczne ustawienie niestandardowego adresu URL podczas tworzenia elementu OpenAIClient. Można również użyć różnych mechanizmów uwierzytelniania w zależności od usługi.

Jeśli wymagany jest niestandardowy adres URL (zobacz tabelę powyżej), możesz ustawić go za pomocą elementu OpenAIClientOptions.

var clientOptions = new OpenAIClientOptions() { Endpoint = new Uri(serviceUrl) };

Podczas tworzenia klienta można użyć klucza interfejsu API.

OpenAIClient client = new OpenAIClient(new ApiKeyCredential(apiKey), clientOptions);

W przypadku korzystania z usługi platformy Azure można również użyć poświadczeń platformy Azure zamiast klucza interfejsu API.

OpenAIClient client = new OpenAIClient(new BearerTokenPolicy(new AzureCliCredential(), "https://ai.azure.com/.default"), clientOptions)

Po utworzeniu OpenAIClient możesz uzyskać podklienta dla konkretnej usługi, której chcesz użyć, a następnie utworzyć AIAgent na jego podstawie.

AIAgent agent = client
    .GetChatClient(model)
    .CreateAIAgent(instructions: "You are good at telling jokes.", name: "Joker");

Korzystanie z zestawu Azure OpenAI SDK

Ten zestaw SDK może służyć do nawiązywania połączenia zarówno z usługami Azure OpenAI, jak i Azure AI Foundry Models. Tak czy inaczej, podczas tworzenia AzureOpenAIClientpliku należy podać prawidłowy adres URL usługi. Zapoznaj się z powyższą tabelą, aby uzyskać prawidłowy adres URL do użycia.

AIAgent agent = new AzureOpenAIClient(
    new Uri(serviceUrl),
    new AzureCliCredential())
     .GetChatClient(deploymentName)
     .CreateAIAgent(instructions: "You are good at telling jokes.", name: "Joker");

Korzystanie z zestawu SDK trwałych agentów usługi Azure AI

Ten zestaw SDK jest obsługiwany tylko w przypadku usługi Azure AI Foundry Agents. Zapoznaj się z powyższą tabelą, aby uzyskać prawidłowy adres URL do użycia.

var persistentAgentsClient = new PersistentAgentsClient(serviceUrl, new AzureCliCredential());
AIAgent agent = await persistentAgentsClient.CreateAIAgentAsync(
    model: deploymentName,
    name: "Joker",
    instructions: "You are good at telling jokes.");

Proste agenty oparte na usługach wnioskowania

Struktura agentów ułatwia tworzenie prostych agentów na podstawie wielu różnych usług wnioskowania. Każda usługa wnioskowania, która zapewnia implementację klienta czatu, może służyć do kompilowania tych agentów.

Te programy wspierają szeroką gamę funkcji dostępnych od razu:

1. Wywoływanie funkcji
2. Konwersacje wielowątkowe z zarządzaniem lokalną historią czatu lub zarządzanie historią czatu jako usługa
3. Narzędzia dostarczane przez dostosowaną usługę (np. MCP, wykonywanie kodu)
4. Strukturalne dane wyjściowe
5. Odpowiedzi streamingowe

Aby utworzyć jednego z tych agentów, po prostu skonstruuj ChatAgent przy użyciu wybranej implementacji klienta czatu.

from agent_framework import ChatAgent
from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import DefaultAzureCredential

async with (
    DefaultAzureCredential() as credential,
    ChatAgent(
        chat_client=AzureAIAgentClient(async_credential=credential),
        instructions="You are a helpful assistant"
    ) as agent
):
    response = await agent.run("Hello!")

Alternatywnie możesz użyć metody wygody na kliencie czatu:

from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import DefaultAzureCredential

async with DefaultAzureCredential() as credential:
    agent = AzureAIAgentClient(async_credential=credential).create_agent(
        instructions="You are a helpful assistant"
    )

Szczegółowe przykłady można znaleźć w poniższych sekcjach dokumentacji specyficznych dla agenta.

Obsługiwane typy agentów

Narzędzia funkcji

Możesz udostępnić agentom narzędzia funkcji na potrzeby rozszerzonych możliwości:

from typing import Annotated
from pydantic import Field
from azure.identity.aio import DefaultAzureCredential
from agent_framework.azure import AzureAIAgentClient

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 sunny with a high of 25°C."

async with (
    DefaultAzureCredential() as credential,
    AzureAIAgentClient(async_credential=credential).create_agent(
        instructions="You are a helpful weather assistant.",
        tools=get_weather
    ) as agent
):
    response = await agent.run("What's the weather in Seattle?")

Aby zapoznać się z kompletnymi przykładami narzędzi funkcji, zobacz:

• Sztuczna inteligencja platformy Azure z narzędziami funkcji
• Azure OpenAI z narzędziami funkcjonalnymi
• OpenAI z narzędziami funkcjonalnymi

Odpowiedzi w strumieniowaniu

Agenci obsługują zarówno regularne, jak i przesyłane strumieniowo odpowiedzi:

# Regular response (wait for complete result)
response = await agent.run("What's the weather like in Seattle?")
print(response.text)

# Streaming response (get results as they are generated)
async for chunk in agent.run_stream("What's the weather like in Portland?"):
    if chunk.text:
        print(chunk.text, end="", flush=True)

Aby zapoznać się z przykładami przesyłania strumieniowego, zobacz:

• Przykłady przesyłania strumieniowego usługi Azure AI
• Przykłady przesyłania strumieniowego usługi Azure OpenAI
• Przykłady strumieniowego przesyłania OpenAI

Narzędzia interpretera kodu

Agenci sztucznej inteligencji platformy Azure obsługują narzędzia interpretera kodu hostowanego do wykonywania kodu w języku Python:

from agent_framework import ChatAgent, HostedCodeInterpreterTool
from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import DefaultAzureCredential

async with (
    DefaultAzureCredential() as credential,
    ChatAgent(
        chat_client=AzureAIAgentClient(async_credential=credential),
        instructions="You are a helpful assistant that can execute Python code.",
        tools=HostedCodeInterpreterTool()
    ) as agent
):
    response = await agent.run("Calculate the factorial of 100 using Python")

Aby zapoznać się z przykładami interpretera kodu, zobacz:

• Sztuczna inteligencja platformy Azure z interpreterem kodu
• Asystenci Azure OpenAI z interpretatorem kodu
• Asystenty OpenAI z interpreterem kodu

Agenty niestandardowe

Istnieje również możliwość utworzenia w pełni niestandardowych agentów, które nie są po prostu nakładkami wokół klienta czatu. Struktura agenta udostępnia protokół i AgentProtocol klasę BaseAgent bazową, która po zaimplementowaniu/podklasie umożliwia pełną kontrolę nad zachowaniem i możliwościami agenta.

from agent_framework import BaseAgent, AgentRunResponse, AgentRunResponseUpdate, AgentThread, ChatMessage
from collections.abc import AsyncIterable

class CustomAgent(BaseAgent):
    async def run(
        self,
        messages: str | ChatMessage | list[str] | list[ChatMessage] | None = None,
        *,
        thread: AgentThread | None = None,
        **kwargs: Any,
    ) -> AgentRunResponse:
        # Custom agent implementation
        pass

    def run_stream(
        self,
        messages: str | ChatMessage | list[str] | list[ChatMessage] | None = None,
        *,
        thread: AgentThread | None = None,
        **kwargs: Any,
    ) -> AsyncIterable[AgentRunResponseUpdate]:
        # Custom streaming implementation
        pass