Schnellstart: Erstellen von Agents mithilfe der Antwort-API

In dieser Schnellstartanleitung rufen Sie die Antwort-API für einen Foundry-Projektendpunkt aus Ihrem eigenen Code auf, um einen kurzlebigen Agent zu erstellen – ein Agent, dessen Definition (Anweisungen, Tools, Modell) in Ihrem Anwendungscode anstelle einer dauerhaften Ressource im Foundry Agent Service gespeichert ist. Jeder Aufruf erstellt den Agent in Ihrem Prozess und ruft die Antwort-API für Modellinference und Tool-Orchestrierung auf.

Dieses Muster passt zu Entwicklern, ISVs und digitalen Nativen, die ihre Agentdefinitionen mit dem Rest ihres Anwendungscodes versenden und versionieren möchten, anstatt als Out-of-Band-Ressource, die jemand mit der App synchronisieren muss. Im Gegensatz zu den Eingabeaufforderungs-Agents gibt es keine Agentressource zum Erstellen, Aktualisieren oder Löschen in Foundry – die Lebenszyklusverwaltung wird durch direktes Aufrufen der Antwort-API ersetzt.

Die Responses-API ist der zentrale Einstiegspunkt für Modelle und Tools in Foundry. Sie können es auf zwei verschiedenen Endpunkten aufrufen:

  • Endpunkt des Foundry-Projekts (diese Schnellstartanleitung, empfohlen) – vollständige Foundry-Unterstützung. Macht Foundry-Modelle aus dem Katalog und den Plattformtools (Dateisuche, Codedolmetscher, Speicher, Websuche, MCP, SharePoint, WorkIQ, Fabric IQ und mehr) über eine einzelne projektbezogene API-Oberfläche verfügbar, die bei {project_endpoint}/openai/v1/responses erreicht wurde.
  • Azure OpenAI-Endpunkt – beste Latenz und maximale Kompatibilität mit vorhandenen OpenAI-Clients. Verwenden Sie diese Option, wenn Sie nur OpenAI-Modelle und Standard-OpenAI-Tools benötigen und keine Foundry-spezifischen Funktionen benötigen.

Der empfohlene Pfad ist das Agent-Framework, das die Authentifizierung, die Toolverkabelung und die Nachrichten-Orchestrierung für Sie verarbeitet. In Python ist dies FoundryChatClient; in .NET ist es AIProjectClient.AsAIAgent(...). Das OpenAI SDK funktioniert auch gegen diesen Endpunkt und wird als Alternative in der Direkten Verwendung des OpenAI SDK behandelt.

Wenn Sie kein Azure-Abonnement besitzen, können Sie ein kostenloses Konto erstellen.

Wann das Muster für kurzlebige Agenten verwendet werden sollte

Verwenden Sie dieses Muster, wenn Sie Agent-Code außerhalb von Foundry hosten – potenziell in Ihre eigene Anwendung eingebettet – aber auf Foundry-Agent-Features wie Modelle und Plattformtools zugreifen möchten.

Das ephemere Muster und gehostete Agenten sind ergänzend, keine Alternativen. Derselbe Agent Framework-Agentcode kann auch als gehosteter Agent gepackt und über die Foundry Agents-API verfügbar gemacht werden. Dies ist nützlich, wenn Sie einen foundry-verwalteten Endpunkt benötigen, den andere Apps, Dienste oder Agents aufrufen können. Sie können beides aus einer Codebasis ausführen: Führen Sie den Agent in einem Prozess aus, in dem er mit Ihrer App ausgeliefert wird, und veröffentlichen Sie dieselbe Definition wie ein gehosteter Agent, in dem andere Anrufer sie benötigen.

Was der Foundry-Projektendpunkt zusätzlich zur OpenAI Responses-API bietet

Die Antwort-API auf einem Foundry-Projektendpunkt ist mit der OpenAI-Antwort-API kompatibel, sodass vorhandene OpenAI-Clients mit minimalen Änderungen daran arbeiten. Der Foundry-Projektendpunkt fügt Folgendes oben hinzu:

  • Projektbezogene Daten: Dateien, Vektorspeicher und andere Daten werden auf project-Ebene statt auf Ressourcenebene gespeichert, wodurch Daten pro Projekt isoliert werden und Sie eigene Ressourcen über die Standard-Agent-Einrichtung nutzen können.
  • Foundry Models zusätzlich zu OpenAI: Foundry Models, die direkt über Azure (nicht nur OpenAI-Modelle) verkauft werden, sind über dieselbe API verfügbar.
  • Foundry-spezifische Tools: Plattformtools wie SharePoint, WorkIQ und Fabric IQ stehen neben den Standard-OpenAI-Tools zur Verfügung.
  • On-behalf-of-Authentifizierung (OBO) für Tools: Tools können nachgelagerte Dienste im Namen des angemeldeten Benutzers aufrufen, nicht nur mit der Anwendungsidentität.
  • Beobachtbarkeit und Governance auf Projektebene: Aufrufe, die über den Projektendpunkt erfolgen, durchlaufen ohne zusätzliche Konfiguration die Ablaufverfolgung, Überwachung, Inhaltsfilter und Identitätskonfiguration des Projekts (siehe Beobachtbarkeit und Unternehmensfunktionen).

Das Aufrufen des Projektendpunkts – kein OpenAI-Endpunkt auf Ressourcenebene – entsperrt diese projektbezogenen Funktionen.

Voraussetzungen

  • Python 3.10 oder höher installiert.

Festlegen von Umgebungsvariablen

Speichern Sie Ihren Projektendpunkt und den bereitgestellten Modellnamen als Umgebungsvariablen. Die folgenden Beispiele lesen diese Werte aus der Umgebung.

FOUNDRY_PROJECT_ENDPOINT=<endpoint copied from welcome screen>
FOUNDRY_MODEL=<your deployed model name>

Pakete installieren

Installieren Sie das Agent Framework-Paket mit dem Foundry-Anbieter:

pip install agent-framework-foundry aiohttp

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

Microsoft.Agents.AI.Foundry stellt die AsAIAgent(...) Erweiterungsmethode für AIProjectClient bereit und bringt transitiv Microsoft.Agents.AI ein.

Einen Agent erstellen

Erstellen Sie einen ephemeren Agent, der lokal in Ihrem Prozess ausgeführt wird, und ruft die Antwort-API für Modellinference und Tool-Orchestrierung auf.

Verwenden Sie FoundryChatClient und die Agent-Klasse.

import asyncio
import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

async def main() -> None:
    agent = Agent(
        client=FoundryChatClient(
            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
            model=os.environ["FOUNDRY_MODEL"],
            credential=AzureCliCredential(),
        ),
        instructions="You are a helpful assistant.",
    )

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

if __name__ == "__main__":
    asyncio.run(main())

Die Ausgabe gibt die Antwort des Agenten aus. Da der Agent kurzlebig ist, wird keine Definition für den Dienst beibehalten – sie ist nur für die Lebensdauer des Python Prozesses vorhanden.

Verwenden Sie AIProjectClient.AsAIAgent(...) aus dem Microsoft Agent Framework, um den Foundry-Projektendpunkt als AIAgent umzuschließen.

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

string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
string deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL")
    ?? throw new InvalidOperationException("FOUNDRY_MODEL is not set.");

AIAgent agent =
    new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
    .AsAIAgent(
        model: deploymentName,
        instructions: "You are a helpful assistant.",
        name: "Assistant");

Console.WriteLine($"Agent: {await agent.RunAsync("What is the capital of France?")}");

Die Ausgabe gibt die Antwort des Agenten aus. Da der Agent kurzlebig ist, wird keine Definition für den Dienst beibehalten – es ist nur für die Lebensdauer des Prozesses vorhanden.

Hinzufügen von Funktionstools

Definieren Sie lokale Funktionstools, und übergeben Sie sie an den Agent. Der Agent ruft diese Tools automatisch bei Bedarf während einer Unterhaltung auf.

Definieren Sie lokale Funktionstools mithilfe des @tool Dekorators.

import asyncio
import os
from random import randint
from typing import Annotated

from agent_framework import Agent, tool
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential
from pydantic import Field

@tool(approval_mode="never_require")
def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
) -> str:
    """Get the weather for a given location."""
    conditions = ["sunny", "cloudy", "rainy", "stormy"]
    return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."

async def main() -> None:
    agent = Agent(
        client=FoundryChatClient(
            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
            model=os.environ["FOUNDRY_MODEL"],
            credential=AzureCliCredential(),
        ),
        instructions="You are a helpful weather agent.",
        tools=get_weather,
    )

    result = await agent.run("What's the weather like in Seattle?")
    print(f"Agent: {result}")

if __name__ == "__main__":
    asyncio.run(main())

Der Agent verwendet die Antwort-API, um zu bestimmen, wann die get_weather Funktion aufgerufen, lokal ausgeführt wird, und gibt das Ergebnis in natürlicher Sprache zurück.

Definieren Sie eine lokale Methode, versehen Sie sie mit [Description] Attributen, und umschließen Sie sie mit AIFunctionFactory.Create(...).

using System.ComponentModel;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

[Description("Get the weather for a given location.")]
static string GetWeather(
    [Description("The location to get the weather for.")] string location)
{
    string[] conditions = ["sunny", "cloudy", "rainy", "stormy"];
    Random rng = Random.Shared;
    return $"The weather in {location} is {conditions[rng.Next(conditions.Length)]} with a high of {rng.Next(10, 31)}°C.";
}

AITool weatherTool = AIFunctionFactory.Create(GetWeather);

string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
string deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL")
    ?? throw new InvalidOperationException("FOUNDRY_MODEL is not set.");

AIAgent agent =
    new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
    .AsAIAgent(
        model: deploymentName,
        instructions: "You are a helpful weather agent.",
        name: "WeatherAssistant",
        tools: [weatherTool]);

Console.WriteLine($"Agent: {await agent.RunAsync("What's the weather like in Seattle?")}");

Der Agent verwendet die Antwort-API, um zu bestimmen, wann sie aufgerufen GetWeatherwerden soll, führt sie lokal aus und gibt das Ergebnis in natürlicher Sprache zurück.

Verwenden des Websuchtool

Die Antwort-API auf dem Endpunkt des Foundry-Projekts bietet integrierte gehostete Tools wie die Websuche. Gewähren Sie Ihrem Agent Zugriff auf die Websuche ohne lokale Implementierung.

Verwenden Sie FoundryChatClient.get_web_search_tool():

import asyncio
import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

async def main() -> None:
    agent = Agent(
        client=FoundryChatClient(
            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
            model=os.environ["FOUNDRY_MODEL"],
            credential=AzureCliCredential(),
        ),
        instructions="You are a research assistant. Use web search to find current information.",
        tools=[
            FoundryChatClient.get_web_search_tool(),
        ],
    )

    result = await agent.run("What are the latest updates to Microsoft Foundry?")
    print(f"Agent: {result}")

if __name__ == "__main__":
    asyncio.run(main())

Das Websuchtool wird serverseitig über die Responses API des Foundry-Projekts ausgeführt. Sie können es mit lokalen Funktionstools kombinieren, um Ihrem Agent sowohl Webzugriff als auch benutzerdefinierte Codefunktionen zu ermöglichen:

agent = Agent(
    client=FoundryChatClient(
        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        model=os.environ["FOUNDRY_MODEL"],
        credential=AzureCliCredential(),
    ),
    instructions="You are a helpful assistant with web and weather capabilities.",
    tools=[
        FoundryChatClient.get_web_search_tool(),
        get_weather,  # Local function tool defined with @tool
    ],
)

Übergeben Sie new HostedWebSearchTool() in der tools-Liste:

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

string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
string deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL")
    ?? throw new InvalidOperationException("FOUNDRY_MODEL is not set.");

AIAgent agent =
    new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
    .AsAIAgent(
        model: deploymentName,
        instructions: "You are a research assistant. Use web search to find current information.",
        name: "ResearchAssistant",
        tools: [new HostedWebSearchTool()]);

Console.WriteLine($"Agent: {await agent.RunAsync("What are the latest updates to Microsoft Foundry?")}");

Das Websuchwerkzeug wird serverseitig über die Responses API des Foundry-Projekts ausgeführt. Sie können es mit lokalen Funktionstools kombinieren, um Ihrem Agent sowohl Webzugriff als auch benutzerdefinierte Codefunktionen zu ermöglichen:

AIAgent agent =
    new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
    .AsAIAgent(
        model: deploymentName,
        instructions: "You are a helpful assistant with web and weather capabilities.",
        name: "Assistant",
        tools: [new HostedWebSearchTool(), weatherTool]);

Antworten streamen

Empfangen Sie Antworten, während sie generiert werden, anstatt auf die vollständige Nachricht zu warten.

Verwenden Sie den stream=True Parameter:

import asyncio
import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

async def main() -> None:
    agent = Agent(
        client=FoundryChatClient(
            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
            model=os.environ["FOUNDRY_MODEL"],
            credential=AzureCliCredential(),
        ),
        instructions="You are a helpful assistant.",
    )

    print("Agent: ", 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()

if __name__ == "__main__":
    asyncio.run(main())

Rufen Sie RunStreamingAsync auf und iterieren Sie den AgentResponseUpdate-Stream:

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

string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
string deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL")
    ?? throw new InvalidOperationException("FOUNDRY_MODEL is not set.");

AIAgent agent =
    new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
    .AsAIAgent(
        model: deploymentName,
        instructions: "You are a helpful assistant.",
        name: "Assistant");

Console.Write("Agent: ");
await foreach (AgentResponseUpdate update in agent.RunStreamingAsync("Tell me a fun fact."))
{
    Console.Write(update);
}
Console.WriteLine();

Die Streamingausgabe wird in der Konsole schrittweise angezeigt, während das Modell jedes Token generiert.

Observability und Enterprise-Funktionen

Ephemer bedeutet nicht, dass etwas unverwaltet ist. Da Aufrufe den Projektendpunkt durchlaufen, erben sie die Unternehmenskonfiguration des Projekts ohne zusätzliche Verkabelung:

  • Nachverfolgung und Überwachung: Anfragen, Toolaufrufe und die Tokennutzung werden in Foundry Observability für das Projekt erfasst.
  • Inhaltsfilter und Governance: Inhaltsfilter auf Projektebene und Richtlinien für verantwortungsvolle KI gelten für jeden Aufruf.
  • Identität und Zugriff: Aufrufe authentifizieren sich anhand der Identitätskonfiguration des Projekts; OBO-fähige Tools können als der angemeldete Benutzer fungieren.

Das kurzlebige Muster ist keine eingeschränkte Funktionsebene – Sie erhalten dieselben Foundry-Modelle, Tools, Observability und Governance, unabhängig davon, ob Sie den Agent im Prozess ausführen oder denselben Code wie ein gehosteter Agent verpacken. Bei der Wahl geht es um die Bereitstellungsform, nicht um den Funktionsumfang.

Verwenden Sie direkt das OpenAI SDK

Da die Foundry-Projektantwort-API openAI-kompatibel ist, können Sie sie auch direkt aus dem OpenAI SDK aufrufen, indem Sie den Client auf den Projektendpunkt ({project_endpoint}/openai/v1/responses) verweisen. Verwenden Sie diesen Pfad nur, wenn Sie bereits über OpenAI SDK-Code verfügen oder eine Steuerung auf niedrigerer Ebene über die Anforderungs- und Antwort-Shapes benötigen. Neuer Code sollte das Agent-Framework bevorzugen, das die Authentifizierung, die Werkzeugverkabelung und die Orchestrierung für Sie verarbeitet.

Sdk-Beispiele finden Sie unter:

Foundry Responses Beispiele (azure-ai-projects)

Azure. AI. OpenAI-Beispiele

Bereinigen von Ressourcen

Da die hier erstellten Agent Framework-Agents kurzlebig sind, ist keine dienstseitige Bereinigung erforderlich. Der Agent ist nur in Ihrem lokalen Prozess vorhanden. Wenn Sie Findry-Ressourcen erstellt haben, die Sie nicht mehr benötigen, löschen Sie sie im Foundry-Portal.

Verwandte Inhalte

Ausführlichere Informationen zu diesem Muster

Packen sie den gleichen Agentcode wie ein gehosteter Agent

  • Last updated on