Microsoft Foundry-Agentendienst

Installieren der Pakete

dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.Identity
dotnet add package Microsoft.Agents.AI.Foundry --prerelease

Mit einem Prompt-Agenten verbinden

Erstellen Sie ein AIProjectClient für das Foundry-Projekt und umschließen Sie ein AgentReference als ein FoundryAgent. Legen Sie die Version fest, wenn die Anwendung eine bestimmte Prompt-Agent-Definition verwenden muss.

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using Microsoft.Agents.AI.Foundry;

var projectClient = new AIProjectClient(
    new Uri(Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")!),
    new DefaultAzureCredential());

FoundryAgent agent = projectClient.AsAIAgent(
    new AgentReference(
        Environment.GetEnvironmentVariable("FOUNDRY_AGENT_NAME")!,
        Environment.GetEnvironmentVariable("FOUNDRY_AGENT_VERSION")!));

Console.WriteLine(await agent.RunAsync("What can you help me with?"));

Sie können auch eine ProjectsAgentRecord abrufen, um deren neueste Version zu verwenden, oder ein ProjectsAgentVersion, um eine explizit abgerufene Version zu verwenden, und das Objekt dann an projectClient.AsAIAgent(...) übergeben.

Abrufen der neuesten Prompt Agent-Version

Verwenden Sie AgentAdministrationClient, wenn die Anwendung die neueste registrierte Version anhand des Namens auflösen soll.

ProjectsAgentRecord agentRecord =
    await projectClient.AgentAdministrationClient.GetAgentAsync(
        Environment.GetEnvironmentVariable("FOUNDRY_AGENT_NAME")!);

FoundryAgent latestAgent = projectClient.AsAIAgent(agentRecord);
Console.WriteLine(await latestAgent.RunAsync("What can you help me with?"));

Herstellen einer Verbindung mit einem gehosteten Agent

Gehostete Agents machen einen agentspezifischen OpenAI-Endpunkt verfügbar. Erstellen Sie den Endpunkt aus dem Projektendpunkt und dem Namen des registrierten Agenten, und übergeben Sie ihn anschließend an AIProjectClient.AsAIAgent(...).

Env.TraversePath().Load();

// Port the Hosted-* samples listen on when run locally with `dotnet run`.
const int LocalAgentPort = 8088;

// AZURE_AI_AGENT_NAME is the registered server-side agent name.
string agentName = Environment.GetEnvironmentVariable("AZURE_AI_AGENT_NAME")
    ?? throw new InvalidOperationException("AZURE_AI_AGENT_NAME is not set.");

// Pick the server to talk to. `--local` and `--remote` mirror the flag `azd ai agent invoke`
// exposes; with neither, ask at startup.
    ══════════════════════════════════════════════════════════
    """);
Console.ResetColor();
Console.WriteLine();

Die vom Administrator kontrollierte Versionsauswahl des Endpunkts bestimmt die aktive Version des gehosteten Agents.

Installieren der Pakete

pip install agent-framework-foundry

Konfiguration

FOUNDRY_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com"
FOUNDRY_AGENT_NAME="my-agent"
FOUNDRY_AGENT_VERSION="1.0"

Verwenden Sie FOUNDRY_AGENT_VERSION für Prompt-Agents. Gehostete Agents können sie weglassen.

Mit einem Prompt-Agenten verbinden

Geben Sie den Projektendpunkt, den Agentnamen und die Agentversion an. Der Dienst stellt das gespeicherte Modell, die Anweisungen und die Konfiguration des gehosteten Tools bereit.

async def main() -> None:
    agent = FoundryAgent(
        project_endpoint="https://your-project.services.ai.azure.com",
        agent_name="my-prompt-agent",
        agent_version="1.0",
        credential=AzureCliCredential(),
    )

    result = await agent.run("What is the capital of France?")
    print(f"Agent: {result}")

    # Streaming
    print("Agent (streaming): ", end="", flush=True)
    async for chunk in agent.run("Tell me a fun fact.", stream=True):
        if chunk.text:
            print(chunk.text, end="", flush=True)
    print()

Wenn ein Prompt-Agent eine lokale Funktionshilfe deklariert, übergeben Sie die passende aufrufbare Funktion über tools= beim Erstellen von FoundryAgent, damit der Client sie bei Bedarf ausführen kann. Sehen Sie sich das Beispiel für das Veröffentlichen und Verbinden von Prompt-Agents an.

Herstellen einer Verbindung mit einem gehosteten Agent

Gehostete Agents benötigen agent_versionnicht. Stellen Sie eine Verbindung mit dem Projektendpunkt und dem Namen des registrierten Agents her.

async def main() -> None:
    # HostedAgents don't need agent_version
    agent = FoundryAgent(
        project_endpoint=os.getenv("FOUNDRY_PROJECT_ENDPOINT"),
        agent_name=os.getenv("FOUNDRY_AGENT_NAME"),
        credential=AzureCliCredential(),
    )

    result = await agent.run("Summarize the latest news about AI.")
    print(f"Agent: {result}")

Was funktioniert und was nicht? FoundryAgent

FoundryAgent stellt eine Verbindung mit einer Agentdefinition her, die bereits in Foundry vorhanden ist. Die gespeicherten Anweisungen und die Konfiguration des Tools sind maßgeblich, sodass sich das clientseitige Verhalten von einer anwendungseigenen Agent(client=FoundryChatClient(...)) unterscheidet.

Tools

Hinweise zur Einbindung der Toolbox und zur direkten MCP-Nutzung finden Sie unter Microsoft Foundry Toolbox.

Sie können zur Konstruktionszeit kein neues modellsichtbares Tool registrieren. Die Übergabe eines Funktions-Callbacks stellt nur die lokale Implementierung für eine Funktion bereit, die der Foundry-Agent bereits deklariert hat.

Kontextanbieter

Verwenden Sie Agent(client=FoundryChatClient(...)), wenn die Anwendung eine dynamische Toolauswahl, das Laden von Skills oder ein Verhalten benötigt, bei dem sich die für das Modell sichtbaren Tools zur Laufzeit verändern.

Ausführungsoptionen

Da die Definition des Foundry-Agenten maßgeblich ist, wird nicht jede über default_options oder agent.run(...) übergebene Option berücksichtigt.

Gehostete Agents erhalten dieselbe clientseitige Filterung, aber der bereitgestellte Agent kann jede weitergeleitete Option akzeptieren, ignorieren oder erneut interpretieren. Überprüfen Sie das Verhalten für den bestimmten gehosteten Agent.

Verwalten einer Gehosteten Agent-Dienstsitzung

Gehostete Agenten, die serverseitige Sitzungen verwenden, erfordern die Vorschauoberfläche für Responses:

Erstellen Sie die Service-Sitzung explizit, wenn die Anwendung sie an einen Mandanten oder Benutzer binden muss, und kapseln Sie deren Kennung anschließend in eine Agent-Framework-Sitzung.

    queries = [
        "Hi!",
        "Your name is Javis. What can you do?",
        "What is your name?",
    ]
    for query in queries:
        print(f"\nUser: {query}")
        print("Agent: ", end="", flush=True)
        async for chunk in agent.run(query, session=session, stream=True):
            if chunk.text:
                print(chunk.text, end="", flush=True)
    print()


async def run_service_managed_session(
    *,
    agent: FoundryAgent,
    project_client: AIProjectClient,
    agent_name: str,
) -> None:
    """Let Foundry create the hosted-agent session, then delete it when finished."""
    session = AgentSession()
    print("\nService-managed hosted-agent session")
    print(f"Before first request: {session.state.get(FOUNDRY_HOSTED_AGENT_SESSION_ID_KEY)}")
    try:
        await run_conversation(agent, session)
        print(f"After conversation: {session.state.get(FOUNDRY_HOSTED_AGENT_SESSION_ID_KEY)}")
    finally:
        hosted_session_id = session.state.get(FOUNDRY_HOSTED_AGENT_SESSION_ID_KEY)
        if isinstance(hosted_session_id, str) and hosted_session_id:
            await project_client.agents.delete_session(agent_name, hosted_session_id)
            print(f"Deleted session: {hosted_session_id}")


async def run_user_managed_session(
    *,
    agent: FoundryAgent,
    project_client: AIProjectClient,
    agent_name: str,
    agent_version: str | None,
) -> None:
    """Create, attach, and delete a hosted-agent session explicitly."""
    resolved_agent_version = agent_version
    if resolved_agent_version is None:
        agent_details = await project_client.agents.get(agent_name)
        resolved_agent_version = agent_details.versions.latest.version

    hosted_session = await project_client.agents.create_session(
        agent_name,
        version_indicator=VersionRefIndicator(agent_version=resolved_agent_version),
    )
    session = AgentSession()
    session.state[FOUNDRY_HOSTED_AGENT_SESSION_ID_KEY] = hosted_session.agent_session_id

    print("\nUser-managed hosted-agent session")
    print(f"Created session: {hosted_session.agent_session_id}")
    try:
        await run_conversation(agent, session)
    finally:
        await project_client.agents.delete_session(agent_name, hosted_session.agent_session_id)
        print(f"Deleted session: {hosted_session.agent_session_id}")


async def main() -> None:
    credential = AzureCliCredential()
    project_endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
    agent_name = os.environ["FOUNDRY_AGENT_NAME"]
    agent_version = os.getenv("FOUNDRY_AGENT_VERSION")

    project_client = AIProjectClient(

Festlegen eines benutzerdefinierten HTTP-Timeouts

FoundryAgent übernimmt standardmäßig das Timeout des OpenAI SDK. Übergeben Sie timeout= in Sekunden, wenn mehrturnige Konversationen oder Netzwerkbedingungen ein anderes Limit erfordern.

from agent_framework.foundry import FoundryAgent
from azure.identity import AzureCliCredential

agent = FoundryAgent(
    project_endpoint="https://your-project.services.ai.azure.com",
    agent_name="my-prompt-agent",
    credential=AzureCliCredential(),
    timeout=120.0,
)

Das Timeout wird auf eine Kopie pro Agent des HTTP-Clients angewendet und wirkt sich nicht auf andere Agents aus, die dasselbe AIProjectClientverwenden.