Agenti Microsoft Foundry

Rozhraní Microsoft Agent Framework podporuje vytváření agentů, kteří používají službu Foundry Agent. Pomocí historie chatu spravovaných službou můžete vytvářet trvalé instance agenta založené na službě.

Začínáme

Přidejte do projektu požadované balíčky NuGet.

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

Vytvoření agentů Foundry

Jako první krok je potřeba vytvořit klienta pro připojení ke službě agenta.

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

Výstraha

DefaultAzureCredential je vhodný pro vývoj, ale vyžaduje pečlivé zvážení v produkčním prostředí. V produkčním prostředí zvažte použití konkrétních přihlašovacích údajů (např ManagedIdentityCredential. ) k zabránění problémům s latencí, neúmyslnému testování přihlašovacích údajů a potenciálním bezpečnostním rizikům z náhradních mechanismů.

Pokud chcete používat službu agenta, musíte ve službě vytvořit prostředek agenta. Můžete to provést pomocí sady Azure.AI.Agents.Persistent SDK nebo pomocníků rozhraní Microsoft Agent Framework.

Použití Persistent SDK

Vytvořte perzistentního agenta a načtěte ho jako pomocí .

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

Použití pomocníků Agent Framework

Můžete také vytvořit a vrátit AIAgent v jednom kroku:

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

Opětovné nasazení agentů Foundry

Existující agenty Foundry můžete znovu použít tak, že je načítáte pomocí jejich ID.

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

Návod

Najdete kompletní spustitelné příklady v ukázkách .NET.

Použití agenta

Agent AIAgent je standardní a podporuje všechny standardní AIAgent operace.

Další informace o tom, jak spouštět agenty a pracovat s nimi, najdete v úvodních kurzech agenta.

Konfigurace

Proměnné prostředí

Důležité

AzureAIAgentClient (Foundry Agent Service v1) a AzureAIClient (Foundry Agent Service v2) vyžadují koncový bod projektu Azure AI Foundry (formát: https://<your-project>.services.ai.azure.com/api/projects/<project-id>), nikoli koncový bod prostředku Azure OpenAI. Abyste mohli tohoto poskytovatele použít, musíte mít projekt Azure AI Foundry . Pokud máte místo toho samostatný prostředek Azure OpenAI, podívejte se na stránku poskytovatele Azure OpenAI.

Před použitím agentů Foundry musíte nastavit tyto proměnné prostředí:

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"

Případně můžete tyto hodnoty zadat přímo ve svém kódu.

Installation

Přidejte do projektu balíček Azure AI pro rozhraní Agent Framework:

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

Začínáme

Autentizace

Agenti Foundry používají k ověřování přihlašovací údaje Azure. Nejjednodušším přístupem je použít AzureCliCredential po spuštění az login. Všichni klienti Azure AI přijímají jednotný credential parametr, který podporuje TokenCredential, AsyncTokenCredentialnebo zprostředkovatele volatelného tokenu – ukládání tokenů do mezipaměti a aktualizace se zpracovává automaticky.

from azure.identity.aio import AzureCliCredential

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

Vytvoření agentů Foundry

Základní vytvoření agenta

Služba agenta Foundry v1

Nejjednodušší způsob, jak vytvořit agenta, je použití AzureAIAgentClient s proměnnými prostředí:

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

Foundry Agent Service v2

Nejjednodušší způsob, jak vytvořit agenta, je použití AzureAIClient s proměnnými prostředí:

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

async def main():
    async with (
        AzureCliCredential() as credential,
        AzureAIClient(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())

Explicitní konfigurace

Služba agenta Foundry v1

Konfiguraci můžete také explicitně zadat místo použití proměnných prostředí:

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

Foundry Agent Service v2

Konfiguraci můžete také explicitně zadat místo použití proměnných prostředí:

import asyncio
from agent_framework.azure import AzureAIClient
from azure.ai.projects.aio import AIProjectClient
from azure.identity.aio import AzureCliCredential

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

asyncio.run(main())

Použití existujících agentů Foundry

Použití existujícího agenta

Služba agenta Foundry v1

Pokud máte existujícího agenta v Foundry, můžete ho použít tak, že zadáte jeho ID:

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

Foundry Agent Service v2

Pokud máte existujícího agenta v Foundry, můžete ho načíst podle názvu pomocí poskytovatele agenta projektu.

import asyncio
import os
from agent_framework.azure import AzureAIProjectAgentProvider
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,
    ):
        provider = AzureAIProjectAgentProvider(project_client=project_client)
        agent = await provider.get_agent(name="<existing-agent-name>")

        result = await agent.run("Hello!")
        print(result)

asyncio.run(main())

Vytváření a správa trvalých agentů

Služba agenta Foundry v1

Pokud chcete mít větší kontrolu nad životním cyklem agenta, můžete vytvořit trvalé agenty pomocí klienta Azure AI Projects:

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

Foundry Agent Service v2

Pokud chcete mít větší kontrolu nad životním cyklem agenta, můžete vytvořit trvalé agenty pomocí klienta Azure AI Projects:

import asyncio
import os
from agent_framework.azure import AzureAIProjectAgentProvider
from azure.ai.projects.aio import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition
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_version(
            agent_name="PersistentAgent",
            definition=PromptAgentDefinition(
                model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
                instructions="You are a helpful assistant."
            ),
        )

        try:
            # Use the agent
            provider = AzureAIProjectAgentProvider(project_client=project_client)
            agent = provider.as_agent(created_agent)

            result = await agent.run("Hello!")
            print(result)
        finally:
            # Clean up the agent
            await project_client.agents.delete_version(
                agent_name=created_agent.name,
                agent_version=created_agent.version
            )

asyncio.run(main())

Funkce agenta

Možnosti odůvodnění a filtrování obsahu

Při vytváření agentů prostřednictvím poskytovatelů projektů Azure AI můžete nastavit default_options, abyste povolili důvodní činnost modelu a filtrování obsahu zodpovědné AI.

Slouží reasoning k vytváření modelů podporujících odůvodnění:

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(

Použijte rai_config k aplikaci nakonfigurované zásady RAI:

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(

Funkční nástroje

Služba agenta Foundry v1

Agentům Foundry můžete poskytnout vlastní nástroje funkcí:

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

Foundry Agent Service v2

Agentům Foundry můžete poskytnout vlastní nástroje funkcí:

import asyncio
from typing import Annotated
from agent_framework.azure import AzureAIClient
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,
        AzureAIClient(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())

Interpretátor kódu

Služba agenta Foundry v1

Agenti Foundry podporují spouštění kódu prostřednictvím interpretu hostovaného kódu:

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

Foundry Agent Service v2

Agenti Foundry podporují spouštění kódu prostřednictvím interpretu hostovaného kódu:

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

async def main():
    async with (
        AzureCliCredential() as credential,
        AzureAIClient(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())

Odpovědi na streamování

Služba agenta Foundry v1

Získávejte odpovědi ihned, jakmile jsou generovány streamováním.

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

Foundry Agent Service v2

Získávejte odpovědi ihned, jakmile jsou generovány streamováním.

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

async def main():
    async with (
        AzureCliCredential() as credential,
        AzureAIClient(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())

Použití agenta

Agent je standardní BaseAgent a podporuje všechny standardní operace agentů.

Další informace o tom, jak spouštět agenty a pracovat s nimi, najdete v úvodních kurzech agenta.

Další kroky

Agenti založené na modelech Foundry