Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
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.
Hinweis
Das ephemere Muster kann sein Modell, seine Anweisungen und Tools bei jeder Anfrage ändern. Die Auswahl des Microsoft Copilot Harness oder das Ausführen des Prompt-Agent-Optimierers wird nicht unterstützt. Diese Funktionen erfordern einen gespeicherten, versionierten Prompt-Agent.
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/responseserreicht 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.
Voraussetzungen
- Ein Modell, das in Microsoft Foundry bereitgestellt wird. Wenn Sie kein Modell haben, führen Sie zuerst Quickstart aus: Einrichten Microsoft Foundry-Ressourcen.
- Mit Ihrem Projekt verbundene Application Insights und Berechtigung zum Lesen von Ablaufverfolgungen. Schließen Sie Application Insights für die Agent-Ablaufverfolgung verbinden ab, auch wenn Sie bereits über ein Projekt und ein Modell verfügen.
- Die Azure CLI ist installiert, und Sie sind angemeldet (
az login).
- Python 3.10 oder höher installiert.
- .NET 8 SDK oder höher installiert.
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: Speichern Sie Dateien, Vektorspeicher und andere Daten auf Projektebene anstelle der Speicherung auf Ressourcenebene. Mit dieser Einrichtung erhalten Sie die Datenisolation pro Projekt und können selbst bereitgestellte Ressourcen über die Standard-Agent-Einrichtung nutzen.
- Foundry Models zusätzlich zu OpenAI: Greifen Sie über dieselbe API auf direkt von Azure verkaufte Foundry Models (nicht nur OpenAI-Modelle) zu.
- Foundry-spezifische Tools: Verwenden Sie Plattformtools wie SharePoint, WorkIQ und Fabric IQ neben den Standard-OpenAI-Tools.
- 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.
- Project-Level-Observability und Governance: Aufrufe erben die Inhaltsfilter- und Identitätskonfiguration des Projekts. Die Ablaufverfolgungen Ihrer Anwendung können die verbundene Application Insights-Ressource des Projekts verwenden (siehe Observability und Enterprise-Funktionen).
Das Aufrufen des Projektendpunkts – kein OpenAI-Endpunkt auf Ressourcenebene – entsperrt diese projektbezogenen Funktionen.
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 Agent-Antwort 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 Agent-Antwort aus. Da der Agent kurzlebig ist, wird für den Dienst keine Definition beibehalten. Er ist nur für die Lebensdauer des Prozesses existent.
Dieser Agent wird in Ihrem eigenen Prozess ausgeführt. Um die Ablaufverfolgungen zu sammeln, konfigurieren Sie die Observability des Agent-Frameworks, führen Sie den Agent erneut aus, und überprüfen Sie die erste Agent-Ablaufverfolgung.
Durch das Verbinden von Application Insights mit Ihrem Foundry-Projekt wird die Ablaufverfolgung in Ihrer Python- oder C#-Anwendung nicht automatisch aktiviert. Konfigurieren Sie die Ablaufverfolgung in der Anwendung, um ihre Agentschritte und lokale Toolaufrufe aufzuzeichnen und diese Ablaufverfolgungen an Application Insights zu senden.
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 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:
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 Unternehmensfunktionen
Ephemer bedeutet nicht, dass etwas unverwaltet ist. Aufrufe über den Projektendpunkt verwenden die Unternehmenskonfiguration des Projekts:
- Ablaufverfolgung und Überwachung: Verwenden Sie die verbundene Application Insights-Ressource des Projekts, um Telemetrie zu speichern. Konfigurieren Sie die Observability des Agent-Frameworks , um Ablaufverfolgungen von Ihren selbst gehosteten Agent- und lokalen Funktionstools zu sammeln.
- 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.
Important
Antwort-IDs sind nicht an einzelne Benutzer gebunden. Bewahren Sie sie vertraulich auf, und überprüfen Sie den Zugriff auf die Konversation, bevor Sie einen vom Client bereitgestellten previous_response_id akzeptieren. Siehe Antwort-IDs und Konversationsverlauf schützen.
Sdk-Beispiele finden Sie unter:
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