Rychlý start: Sestavení agentů pomocí rozhraní API odpovědí

V tomto stručném úvodu ze svého vlastního kódu zavoláte na koncovém bodu projektu Foundry rozhraní Responses API a vytvoříte tak pomíjivého agenta – agenta, jehož definice (instrukce, nástroje, model) je uložena v kódu vaší aplikace namísto toho, aby byla uložená jako trvalý prostředek ve službě Foundry Agent Service. Každé volání vytvoří agenta v procesu a vyvolá rozhraní API pro odpovědi pro odvozování modelů a orchestraci nástrojů.

Tento přístup je vhodný pro vývojáře, nezávislé výrobce softwaru a digitální domorodce, kteří chtějí, aby se definice agentů nasazovaly a verzovaly spolu se zbytkem aplikačního kódu, nikoli jako samostatný externí prostředek, který musí někdo udržovat synchronizovaný s aplikací. Na rozdíl od agentů výzvy neexistuje žádný prostředek agenta k vytvoření, aktualizaci nebo odstranění v Foundry – správa životního cyklu se nahradí voláním rozhraní API pro odpovědi přímo.

Responses API je jediným vstupním bodem pro modely a nástroje ve Foundry. Můžete ji volat pomocí dvou různých koncových bodů:

• Koncový bod projektu Foundry (tento rychlý start, doporučeno) – úplná podpora Foundry Zpřístupňuje modely Foundry z katalogu i z nástrojů platformy (vyhledávání souborů, interpret kódu, paměť, vyhledávání na webu, MCP, SharePoint, WorkIQ, Fabric IQ a další) prostřednictvím jediného rozhraní API na úrovni projektu, které je dostupné na {project_endpoint}/openai/v1/responses.
• Azure koncový bod OpenAI – nejlepší latence a maximální kompatibilita se stávajícími klienty OpenAI. Tuto možnost použijte, pokud potřebujete jenom modely OpenAI a standardní nástroje OpenAI a nepotřebujete funkce specifické pro Foundry.

Doporučená cesta je Agent Framework, která za vás zpracovává ověřování, zapojení nástrojů a orchestraci zpráv. V Python je to FoundryChatClient; v .NET je to AIProjectClient.AsAIAgent(...). OpenAI SDK funguje také pro tento koncový bod a jako alternativa je popsáno v části Použití OpenAI SDK přímo.

Pokud ještě nemáte předplatné Azure, vytvořte si bezplatný účet.

Kdy použít vzor efemérního agenta

Tento vzor použijte, když hostujete kód agenta mimo Foundry – potenciálně vložený do vlastní aplikace – ale chcete získat přístup k funkcím agenta Foundry, jako jsou modely a nástroje platformy.

Dočasný vzor a hostovaní agenti jsou doplňkové, nikoli alternativy. Stejný kód agenta v rámci Agent Framework lze také zabalit jako hostovaného agenta a zpřístupnit prostřednictvím rozhraní API Foundry Agents – to je užitečné, když chcete koncový bod spravovaný službou Foundry, který mohou volat jiné aplikace, služby nebo agenti. Můžete provést obojí z jednoho základu kódu: spusťte agenta v procesu, ve kterém se dodává s vaší aplikací, a publikujte stejnou definici jako hostovaný agent, kde ho potřebují ostatní volající.

Co koncový bod projektu Foundry přidává navíc k rozhraní OpenAI Responses API

Rozhraní API pro odpovědi na koncovém bodu projektu Foundry je kompatibilní s rozhraním API pro odpovědi OpenAI, takže stávající klienti OpenAI s ním pracují s minimálními změnami. Koncový bod projektu Foundry přidá do horní části následující:

• Data vymezená na úrovni projektu: Soubory, vektorová úložiště a další data se ukládají na úrovni project místo na úrovni prostředku, což zajišťuje izolaci dat pro jednotlivé projekty a umožňuje používat vlastní zdroje pomocí standardního nastavení agenta.
• Modely Foundry vedle OpenAI: Modely Foundry prodávané přímo společností Azure (nejen modely OpenAI) jsou dostupné prostřednictvím stejného rozhraní API.
• nástroje specifické pro Foundry: Nástroje platformy, jako jsou SharePoint, WorkIQ a Fabric IQ, jsou k dispozici společně se standardními nástroji OpenAI.
• Ověřování on-behalf-of (OBO) pro nástroje: Nástroje mohou volat následné služby jménem přihlášeného uživatele, nejen pod identitou aplikace.
• Pozorovatelnost a zásady správného řízení na úrovni projektu: Volání uskutečněná přes koncový bod projektu procházejí trasováním, monitorováním, filtry obsahu a konfigurací identity projektu bez nutnosti další konfigurace (viz Pozorovatelnost a podnikové funkce).

Volání koncového bodu projektu – nikoli koncového bodu OpenAI na úrovni prostředku – umožňuje tyto možnosti vázané na projekt.

Předpoklady

• Model nasazený v Microsoft Foundry Pokud model nemáte, nejprve dokončete Quickstart: Nastavení prostředků Microsoft Foundry.
• Nainstalovaný a přihlášený Azure CLI (az login).

• Nainstalovaný Python 3.10 nebo novější

• .NET 8 SDK nebo novější nainstalováno.

Nastavení proměnných prostředí

Uložte koncový bod projektu a nasazený název modelu jako proměnné prostředí. Níže uvedené ukázky načtou tyto hodnoty z prostředí.

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

Instalace balíčků

Nainstalujte balíček Agent Framework s poskytovatelem Foundry:

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 poskytuje metodu rozšíření AsAIAgent(...) na AIProjectClient a tranzitivně přináší Microsoft.Agents.AI.

Vytvořit agenta

Vytvořte dočasného agenta, který se spouští místně v procesu, a volá rozhraní API pro odpovědi pro odvozování modelů a orchestraci nástrojů.

Použijte FoundryChatClient a třídu Agent .

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

Výstup vytiskne odpověď agenta. Vzhledem k tomu, že agent je dočasný, žádná definice se neuchovává do služby – existuje pouze po celou dobu života procesu Python.

Pomocí AIProjectClient.AsAIAgent(...) z frameworku Microsoft Agent zapouzdřete koncový bod projektu ve Foundry jako AIAgent.

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?")}");

Výstup vytiskne odpověď agenta. Vzhledem k tomu, že agent je dočasný, žádná definice se neuchovává ve službě – existuje pouze po celou dobu trvání procesu.

Přidat nástroje funkcí

Definujte místní nástroje funkcí a předejte je agentu. Agent tyto nástroje automaticky volá v případě potřeby během konverzace.

Definujte nástroje místních funkcí pomocí dekorátoru @tool .

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

Agent pomocí rozhraní Responses API určí, kdy zavolat funkci get_weather, spustí ji lokálně a vrátí výsledek v přirozeném jazyce.

Definujte místní metodu, opatřete ji atributy [Description] a zabalte ji do 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?")}");

Agent pomocí rozhraní API odpovědí určí, kdy se má volat GetWeather, provede ho místně a vrátí výsledek v přirozeném jazyce.

Použití nástroje pro vyhledávání na webu

Rozhraní API pro odpovědi na koncovém bodu projektu Foundry poskytuje integrované hostované nástroje, jako je vyhledávání na webu. Přidělte agentovi přístup k vyhledávání na webu bez jakékoli místní implementace.

FoundryChatClient.get_web_search_tool() použijte:

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

Nástroj pro vyhledávání na webu se na straně serveru spouští prostřednictvím rozhraní Responses API projektu Foundry. Můžete ho zkombinovat s místními nástroji funkcí, abyste agentovi poskytli webový přístup i možnosti vlastního kódu:

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
    ],
)

Předejte new HostedWebSearchTool() v seznamu tools:

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?")}");

Nástroj pro vyhledávání na webu se na straně serveru spouští prostřednictvím rozhraní Responses API projektu Foundry. Můžete ho zkombinovat s místními nástroji funkcí, abyste agentovi poskytli webový přístup i možnosti vlastního kódu:

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

Streamovat odpovědi

Dostávejte odpovědi průběžně během jejich generování, místo abyste čekali na celou zprávu.

stream=True Použijte parametr:

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

Zavolejte RunStreamingAsync a iterujte datový proud AgentResponseUpdate:

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

Streamovaný výstup se v konzoli zobrazuje postupně, jak model generuje jednotlivé tokeny.

Pozorovatelnost a možnosti podniku

Dočasný neznamená nespravovaný. Protože volání procházejí přes endpoint projektu, dědí podnikovou konfiguraci projektu bez nutnosti dalšího nastavování:

• Trasování a monitorování: Požadavky, volání nástrojů a využití tokenů se zaznamenávají do monitorování Foundry pro daný projekt.
• Filtry obsahu a správa: Filtry obsahu na úrovni projektu a zásady odpovědné AI se vztahují na každé volání.
• Identita a přístup: Volání se ověřují vůči konfiguraci identity projektu; nástroje s podporou OBO mohou vystupovat jako přihlášený uživatel.

Dočasný vzor není úroveň omezené schopnosti – získáte stejné modely Foundry, nástroje, pozorovatelnost a zásady správného řízení bez ohledu na to, jestli spustíte agenta v procesu nebo zabalíte stejný kód jako hostovaný agent. Volba se týká obrazce nasazení, nikoli sady funkcí.

Přímé použití sady OpenAI SDK

Vzhledem k tomu, že rozhraní API odpovědí projektu Foundry je kompatibilní s OpenAI, můžete ho také volat přímo ze sady OpenAI SDK tak, že klienta nasměrujete na koncový bod projektu ({project_endpoint}/openai/v1/responses). Tuto cestu použijte pouze v případě, že už máte kód sady OpenAI SDK nebo potřebujete kontrolu nad obrazci požadavků a odpovědí na nižší úrovni. Nový kód by měl upřednostňovat rozhraní Agent Framework, které za vás zpracovává ověřování, zapojení nástrojů a orchestraci.

Ukázky sady SDK najdete tady:

Ukázky pro Foundry Responses (azure-ai-projects)

Ukázky Azure.AI.OpenAI

Vyčistěte zdroje

Vzhledem k tomu, že agenti rozhraní Agent Framework vytvořená tady jsou dočasné, není potřeba žádné vyčištění na straně služby. Agent existuje pouze v rámci vašeho lokálního procesu. Pokud jste vytvořili prostředky Foundry, které už nepotřebujete, odstraňte je na portálu Foundry.

Související obsah

Podrobnější informace o tomto vzoru

• Agent Framework na GitHub

• Ukázky poskytovatele Foundry (Python)
• Ukázky API Responses projektu Foundry (OpenAI SDK)

• Agenti s ukázkami pro Foundry (.NET)

Zabalte stejný kód agenta jako hostovaný agent

• Rychlý start: Nasazení prvního hostovaného agenta
• Rychlý start: Vytvoření agenta na podněty
• Co je služba Foundry Agent Service?