Freigeben über

Microsoft Foundry Agents

Microsoft Agent Framework unterstützt das Erstellen von Agents, die den Foundry Agent Service verwenden. Sie können persistente dienstbasierte Agentinstanzen mit dienstverwaltetem Chatverlauf erstellen.

Erste Schritte

Fügen Sie dem Projekt die erforderlichen NuGet-Pakete hinzu.

dotnet add package Azure.Identity
dotnet add package Microsoft.Agents.AI.AzureAI.Persistent --prerelease

Erstellen von Foundry-Agenten

Als erster Schritt müssen Sie einen Client erstellen, um eine Verbindung mit dem Agent-Dienst herzustellen.

using System;
using Azure.AI.Agents.Persistent;
using Azure.Identity;
using Microsoft.Agents.AI;

var persistentAgentsClient = new PersistentAgentsClient(
    "https://<myresource>.services.ai.azure.com/api/projects/<myproject>",
    new DefaultAzureCredential());

Warnung

DefaultAzureCredential ist praktisch für die Entwicklung, erfordert aber sorgfältige Überlegungen in der Produktion. Berücksichtigen Sie in der Produktion die Verwendung bestimmter Anmeldeinformationen (z. B. ManagedIdentityCredential), um Latenzprobleme, unbeabsichtigte Abfragen von Anmeldeinformationen und potenzielle Sicherheitsrisiken durch Ausweichmechanismen zu vermeiden.

Um den Agentdienst zu verwenden, müssen Sie eine Agentressource im Dienst erstellen. Dazu können Sie entweder das Azure.AI.Agents.Persistent SDK oder microsoft Agent Framework-Hilfsprogramme verwenden.

Verwenden des Persistent SDK

Erstellen Sie einen beständigen Agenten und rufen Sie ihn als AIAgent mit PersistentAgentsClient ab.

// Create a persistent agent
var agentMetadata = await persistentAgentsClient.Administration.CreateAgentAsync(
    model: "gpt-4o-mini",
    name: "Joker",
    instructions: "You are good at telling jokes.");

// Retrieve the agent that was just created as an AIAgent using its ID
AIAgent agent1 = await persistentAgentsClient.GetAIAgentAsync(agentMetadata.Value.Id);

// Invoke the agent and output the text result.
Console.WriteLine(await agent1.RunAsync("Tell me a joke about a pirate."));

Verwenden von Agent Framework-Hilfsprogramme

Sie können auch ein AIAgent in einem Schritt erstellen und zurückgeben.

AIAgent agent2 = await persistentAgentsClient.CreateAIAgentAsync(
    model: "gpt-4o-mini",
    name: "Joker",
    instructions: "You are good at telling jokes.");

Wiederverwendung von Gießerei-Agenten

Sie können vorhandene Foundry Agents wiederverwenden, indem Sie sie mithilfe ihrer IDs abrufen.

AIAgent agent3 = await persistentAgentsClient.GetAIAgentAsync("<agent-id>");

Tipp

Vollständige Runnable-Beispiele finden Sie in den .NET-Beispielen .

Verwendung des Agenten

Der Agent ist ein AIAgent Standard und unterstützt alle AIAgent Standardoperationen.

Weitere Informationen zum Ausführen und Interagieren mit Agenten finden Sie in den Agenten-Einführungstutorials.

Konfiguration

Umgebungsvariablen

Von Bedeutung

AzureAIAgentClient (Foundry Agent Service v1) und AzureAIClient (Foundry Agent Service v2) erfordern beide einen Azure AI Foundry-Projektendpunkt (Format: https://<your-project>.services.ai.azure.com/api/projects/<project-id>), nicht einen Azure OpenAI-Ressourcenendpunkt. Sie müssen über ein Azure AI Foundry-Projekt verfügen, um diesen Anbieter zu verwenden. Wenn Sie stattdessen über eine eigenständige Azure OpenAI-Ressource verfügen, lesen Sie die Azure OpenAI-Anbieterseite.

Bevor Sie Foundry Agents verwenden, müssen Sie diese Umgebungsvariablen einrichten:

export AZURE_AI_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com/api/projects/<project-id>"
export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o-mini"

Alternativ können Sie diese Werte direkt in Ihrem Code bereitstellen.

Installation

Fügen Sie Ihrem Projekt das Azure AI-Paket des Agent-Frameworks hinzu:

pip install agent-framework-azure-ai --pre

Erste Schritte

Authentifizierung

Foundry Agents verwenden Azure-Anmeldeinformationen für die Authentifizierung. Der einfachste Ansatz besteht darin, AzureCliCredential nach der Ausführung von az login zu verwenden. Alle Azure AI-Clients akzeptieren einen einheitlichen Parameter credential, der TokenCredential, AsyncTokenCredential oder einen aufrufbaren Tokenanbieter unterstützt. Tokens werden automatisch zwischengespeichert und aktualisiert.

from azure.identity.aio import AzureCliCredential

async with AzureCliCredential() as credential:
    # Use credential with Azure AI agent client

Erstellen von Foundry-Agenten

Grundlegende Agent-Erstellung

Der einfachste Weg, um einen Agenten zu erstellen, ist die Verwendung von AzureAIAgentClient zusammen mit Umgebungsvariablen:

import asyncio
from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import AzureCliCredential

async def main():
    async with (
        AzureCliCredential() as credential,
        AzureAIAgentClient(credential=credential).as_agent(
            name="HelperAgent",
            instructions="You are a helpful assistant."
        ) as agent,
    ):
        result = await agent.run("Hello!")
        print(result.text)

asyncio.run(main())

Explizite Konfiguration

Sie können die Konfiguration auch explizit bereitstellen, anstatt Umgebungsvariablen zu verwenden:

import asyncio
from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import AzureCliCredential

async def main():
    async with (
        AzureCliCredential() as credential,
        AzureAIAgentClient(
            project_endpoint="https://<your-project>.services.ai.azure.com/api/projects/<project-id>",
            model_deployment_name="gpt-4o-mini",
            credential=credential,
            agent_name="HelperAgent"
        ).as_agent(
            instructions="You are a helpful assistant."
        ) as agent,
    ):
        result = await agent.run("Hello!")
        print(result.text)

asyncio.run(main())

Verwenden vorhandener Gießerei-Agenten

Verwenden eines vorhandenen Agents

Wenn Sie über einen vorhandenen Agent in Foundry verfügen, können Sie ihn verwenden, indem Sie dessen ID angeben:

import asyncio
from agent_framework import Agent
from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import AzureCliCredential

async def main():
    async with (
        AzureCliCredential() as credential,
        Agent(
            chat_client=AzureAIAgentClient(
                credential=credential,
                agent_id="<existing-agent-id>"
            ),
            instructions="You are a helpful assistant."
        ) as agent,
    ):
        result = await agent.run("Hello!")
        print(result.text)

asyncio.run(main())

Erstellen und Verwalten persistenter Agenten

Für eine bessere Kontrolle über den Agent-Lebenszyklus können Sie beständige Agents mithilfe des Azure AI Projects-Clients erstellen:

import asyncio
import os
from agent_framework import Agent
from agent_framework.azure import AzureAIAgentClient
from azure.ai.projects.aio import AIProjectClient
from azure.identity.aio import AzureCliCredential

async def main():
    async with (
        AzureCliCredential() as credential,
        AIProjectClient(
            endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
            credential=credential
        ) as project_client,
    ):
        # Create a persistent agent
        created_agent = await project_client.agents.create_agent(
            model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
            name="PersistentAgent",
            instructions="You are a helpful assistant."
        )

        try:
            # Use the agent
            async with Agent(
                chat_client=AzureAIAgentClient(
                    project_client=project_client,
                    agent_id=created_agent.id
                ),
                instructions="You are a helpful assistant."
            ) as agent:
                result = await agent.run("Hello!")
                print(result.text)
        finally:
            # Clean up the agent
            await project_client.agents.delete_agent(created_agent.id)

asyncio.run(main())

Agentfeatures

Optionen zum Filtern von Begründungen und Inhalten

Beim Erstellen von Agents über Azure AI-Projektanbieter können Sie default_options festlegen, um Modellbegründung und verantwortungsvolle KI-Inhaltsfilterung zu aktivieren.

Verwenden Sie reasoning für schlussfolgerungsfähige Modelle:

from agent_framework.azure import AzureAIProjectAgentProvider
from azure.ai.projects.models import Reasoning
from azure.identity.aio import AzureCliCredential
    async with (
        AzureCliCredential() as credential,
        AzureAIProjectAgentProvider(credential=credential) as provider,
    ):
        agent = await provider.create_agent(
    async with (
        AzureCliCredential() as credential,
        AzureAIProjectAgentProvider(credential=credential) as provider,
    ):
        agent = await provider.create_agent(

Um eine konfigurierte RAI-Richtlinie anzuwenden, verwenden Sie rai_config.

from azure.ai.projects.models import RaiConfig
from azure.identity.aio import AzureCliCredential
async def main() -> None:
    print("=== Azure AI Agent with Content Filtering ===\n")

    # Replace with your RAI policy from Azure AI Foundry portal
    rai_policy_name = (
        "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/"
        "Microsoft.CognitiveServices/accounts/{accountName}/raiPolicies/{policyName}"
    )

    async with (
        AzureCliCredential() as credential,
        AzureAIProjectAgentProvider(credential=credential) as provider,
    ):
        # Create agent with content filtering enabled via default_options
        agent = await provider.create_agent(

Funktionstools

Sie können benutzerdefinierte Funktionstools für Foundry-Agents bereitstellen:

import asyncio
from typing import Annotated
from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import AzureCliCredential
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 sunny with a high of 25°C."

async def main():
    async with (
        AzureCliCredential() as credential,
        AzureAIAgentClient(credential=credential).as_agent(
            name="WeatherAgent",
            instructions="You are a helpful weather assistant.",
            tools=get_weather
        ) as agent,
    ):
        result = await agent.run("What's the weather like in Seattle?")
        print(result.text)

asyncio.run(main())

Codedolmetscher

Foundry Agents unterstützen die Codeausführung über den gehosteten Codedolmetscher:

import asyncio
from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import AzureCliCredential

async def main():
    async with (
        AzureCliCredential() as credential,
        AzureAIAgentClient(credential=credential) as client,
        client.as_agent(
            name="CodingAgent",
            instructions="You are a helpful assistant that can write and execute Python code.",
            tools=client.get_code_interpreter_tool(),
        ) as agent,
    ):
        result = await agent.run("Calculate the factorial of 20 using Python code.")
        print(result.text)

asyncio.run(main())

Streaming-Antworten

Erhalten Sie Antworten, während sie mithilfe von Streaming generiert werden:

import asyncio
from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import AzureCliCredential

async def main():
    async with (
        AzureCliCredential() as credential,
        AzureAIAgentClient(credential=credential).as_agent(
            name="StreamingAgent",
            instructions="You are a helpful assistant."
        ) as agent,
    ):
        print("Agent: ", end="", flush=True)
        async for chunk in agent.run("Tell me a short story", stream=True):
            if chunk.text:
                print(chunk.text, end="", flush=True)
        print()

asyncio.run(main())

Den Agent verwenden

Der Agent ist ein Standard BaseAgent und unterstützt alle Standard-Agent-Vorgänge.

Weitere Informationen zum Ausführen und Interagieren mit Agenten finden Sie in den Agenten-Einführungstutorials.

Nächste Schritte

Foundry Model-basierte Agenten

  • Last updated on