Microsoft Agent Framework-Agenttypen

Einfache Agenten basierend auf Inferenzdiensten

Das Agent-Framework erleichtert das Erstellen einfacher Agents basierend auf vielen verschiedenen Ableitungsdiensten. Jeder Rückschlussdienst, der eine Microsoft.Extensions.AI.IChatClient Implementierung bereitstellt, kann zum Erstellen dieser Agents verwendet werden. Dies Microsoft.Agents.AI.ChatClientAgent ist die Agentklasse, die verwendet wird, um einen Agent für jede IChatClient Implementierung bereitzustellen.

Diese Agents unterstützen eine Vielzahl von Funktionen standardmäßig:

1. Aufrufen der Funktion
2. Multi-Turn-Unterhaltungen mit der Verwaltung des lokalen Chatverlaufs oder vom Dienst bereitgestellter Verwaltung des Chatverlaufs
3. Benutzerdefinierte Dienste bieten Tools bereit (z. B. MCP, Codeausführung)
4. Strukturierte Ausgabe

Um einen dieser Agenten zu erstellen, konstruieren Sie einfach ein ChatClientAgent, indem Sie dazu die IChatClient-Implementierung Ihrer Wahl verwenden.

using Microsoft.Agents.AI;

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

Für viele beliebte Dienste haben wir auch Helfer, um die Erstellung dieser Agents noch einfacher zu machen. Weitere Informationen finden Sie in der Dokumentation für jeden Dienst:

Komplexe benutzerdefinierte Agenten

Es ist auch möglich, vollständig benutzerdefinierte Agenten zu erstellen, die nicht bloß Wrapper um eine IChatClient sind. Das Agentframework stellt den AIAgent Basistyp bereit. Dieser Basistyp ist die Kernstraktion für alle Agents, die bei Unterklassen die vollständige Kontrolle über das Verhalten und die Funktionen des Agents ermöglicht.

Weitere Informationen finden Sie in der Dokumentation für benutzerdefinierte Agenten.

Proxys für Remote-Agents

Das Agent-Framework bietet standardmäßig AIAgent Implementierungen für gängige servicegehostete Agentenprotokolle wie A2A. Auf diese Weise können Sie problemlos eine Verbindung mit Remote-Agents aus Ihrer Anwendung herstellen und verwenden.

Weitere Informationen finden Sie in der Dokumentation für jeden Agenttyp:

Referenz zu Azure- und OpenAI SDK-Optionen

Bei Verwendung von Azure AI Foundry-, Azure OpenAI- oder OpenAI-Diensten stehen Ihnen verschiedene SDK-Optionen zur Verbindung mit diesen Diensten zur Verfügung. In einigen Fällen ist es möglich, mehrere SDKs zu verwenden, um eine Verbindung mit demselben Dienst herzustellen oder dasselbe SDK zum Herstellen einer Verbindung mit verschiedenen Diensten zu verwenden. Hier ist eine Liste der verschiedenen Optionen, die Sie nutzen sollten, wenn Sie mit der entsprechenden URL eine Verbindung herstellen. Stellen Sie sicher, dass Sie <resource> und <project> durch Ihre tatsächlichen Ressourcen- und Projektnamen ersetzen.

1. Upgrade von Azure OpenAI auf Azure AI Foundry
2. Wir empfehlen die Verwendung des OpenAI SDK.
3. Obwohl wir empfehlen, das OpenAI SDK für den Zugriff auf Azure AI Foundry-Modelle zu verwenden, unterstützen Azure AI Foundry Models Modelle von vielen verschiedenen Anbietern, nicht nur OpenAI. Alle diese Modelle werden über das OpenAI SDK unterstützt.

Verwenden des OpenAI SDK

Wie in der obigen Tabelle gezeigt, kann das OpenAI SDK verwendet werden, um eine Verbindung mit mehreren Diensten herzustellen. Je nach Dienst, mit dem Sie eine Verbindung herstellen, müssen Sie möglicherweise beim Erstellen einer OpenAIClient eine benutzerdefinierte URL festlegen. Sie können je nach Dienst auch unterschiedliche Authentifizierungsmechanismen verwenden.

Wenn eine benutzerdefinierte URL erforderlich ist (siehe tabelle oben), können Sie sie über openAIClientOptions festlegen.

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

Es ist möglich, beim Erstellen des Clients einen API-Schlüssel zu verwenden.

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

Wenn Sie einen Azure-Dienst verwenden, ist es auch möglich, Azure-Anmeldeinformationen anstelle eines API-Schlüssels zu verwenden.

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

Nachdem Sie den OpenAIClient erstellt haben, können Sie einen Unterclient für den spezifischen Dienst abrufen, den Sie verwenden möchten, und dann eine AIAgent daraus erstellen.

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

Verwenden des Azure OpenAI SDK

Dieses SDK kann verwendet werden, um eine Verbindung mit Azure OpenAI- und Azure AI Foundry Models-Diensten herzustellen. In beiden Fällen müssen Sie beim Erstellen der AzureOpenAIClient die richtige Service-URL angeben. In der obigen Tabelle finden Sie die richtige ZU verwendende URL.

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

Verwenden des Azure AI Persistent Agents SDK

Dieses SDK wird nur mit dem Azure AI Foundry Agents-Dienst unterstützt. In der obigen Tabelle finden Sie die richtige ZU verwendende URL.

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

Einfache Agenten basierend auf Inferenzdiensten

Das Agent-Framework erleichtert das Erstellen einfacher Agents basierend auf vielen verschiedenen Ableitungsdiensten. Jeder Rückschlussdienst, der eine Chatclientimplementierung bereitstellt, kann zum Erstellen dieser Agents verwendet werden.

Diese Agents unterstützen eine Vielzahl von Funktionen standardmäßig:

1. Aufrufen der Funktion
2. Multi-Turn-Unterhaltungen mit der Verwaltung des lokalen Chatverlaufs oder vom Dienst bereitgestellter Verwaltung des Chatverlaufs
3. Benutzerdefinierte Dienste bieten Tools bereit (z. B. MCP, Codeausführung)
4. Strukturierte Ausgabe
5. Streamingantworten

Um einen dieser Agenten zu erstellen, konstruieren Sie einfach ein ChatAgent, wobei Sie die Chat-Client-Implementierung Ihrer Wahl verwenden.

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!")

Alternativ können Sie die Komfortmethode auf dem Chatclient verwenden:

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

Ausführliche Beispiele finden Sie in den unten aufgeführten Abschnitten zu agentspezifischen Dokumentationen.

Unterstützte Agenttypen

Funktionstools

Sie können den Agenten Tools für erweiterte Funktionen bereitstellen.

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?")

Vollständige Beispiele mit Funktionstools finden Sie unter:

• Azure AI mit Funktionstools
• Azure OpenAI mit Funktionstools
• OpenAI mit Funktionstools

Streaming-Antworten

Agenten unterstützen sowohl normale als auch Streaming-Antworten.

# 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)

Beispiele für Streaming finden Sie unter:

• Azure AI-Streamingbeispiele
• Azure OpenAI-Streamingbeispiele
• OpenAI-Streamingbeispiele

Codedolmetschertools

Azure AI-Agents unterstützen gehostete Codedolmetschertools zum Ausführen von Python-Code:

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

Beispiele für Codedolmetscher finden Sie unter:

• Azure AI mit Codedolmetscher
• Azure OpenAI-Assistenten mit Code-Interpreter
• OpenAI Assistants mit Code-Interpreter

Benutzerdefinierte Agents

Es ist auch möglich, vollständig benutzerdefinierte Agents zu erstellen, die nicht nur Wrapper um einen Chatclient herum sind. Agent Framework stellt die AgentProtocol Protokoll- und BaseAgent Basisklasse bereit, die bei Implementierung/Unterklassen die vollständige Kontrolle über das Verhalten und die Funktionen des Agents ermöglicht.

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