Szybki start: tworzenie agentów przy użyciu Responses API

W tym przewodniku Szybki start wywołasz Responses API w punkcie końcowym projektu w Foundry we własnym kodzie, aby utworzyć efemerycznego agenta — agenta, którego definicja (instrukcje, narzędzia, model) znajduje się w kodzie aplikacji, zamiast być utrwalona jako zasób w usłudze Foundry Agent Service. Każde wywołanie tworzy agenta w Twoim procesie i wywołuje interfejs Responses API do wnioskowania modelowego oraz orkiestracji narzędzi.

Ten wzorzec jest odpowiedni dla deweloperów, niezależnych dostawców oprogramowania (ISV) i firm cyfrowych, którzy chcą, aby definicje agentów były wdrażane i wersjonowane razem z pozostałą częścią kodu aplikacji, a nie jako oddzielny zasób, który ktoś musi utrzymywać w synchronizacji z aplikacją. W przeciwieństwie do agentów monitów nie ma zasobu agenta do tworzenia, aktualizowania ani usuwania w rozwiązaniu Foundry — zarządzanie cyklem życia jest zastępowane bezpośrednio przez wywołanie interfejsu API odpowiedzi.

Responses API to jeden punkt wejścia dla modelu i narzędzi w Foundry. Można go wywołać w dwóch różnych punktach końcowych:

  • Punkt końcowy projektu Foundry (ten przewodnik, zalecane) — pełna obsługa Foundry. Udostępnia modele Foundry z katalogu oraz narzędzia platformy (wyszukiwanie plików, interpreter kodu, pamięć, wyszukiwanie w sieci, MCP, SharePoint, WorkIQ, Fabric IQ i nie tylko) za pośrednictwem jednego interfejsu API ograniczonego do projektu, dostępnego pod adresem {project_endpoint}/openai/v1/responses.
  • Punkt końcowy usługi Azure OpenAI — najmniejsze opóźnienia i maksymalna zgodność z istniejącymi klientami OpenAI. Użyj tej funkcji, gdy potrzebujesz tylko modeli OpenAI i standardowych narzędzi OpenAI i nie potrzebujesz funkcji specyficznych dla rozwiązania Foundry.

Zalecaną ścieżką jest Agent Framework, który obsługuje uwierzytelnianie, integrację narzędzi i koordynację komunikatów. W Python jest to FoundryChatClient; w .NET jest AIProjectClient.AsAIAgent(...). Zestaw OpenAI SDK działa również w odniesieniu do tego punktu końcowego i jest omówiony jako alternatywa bezpośrednio w temacie Korzystanie z zestawu OpenAI SDK.

Jeśli nie masz subskrypcji platformy Azure, utwórz bezpłatne konto.

Kiedy należy używać wzorca agenta efemerycznego

Użyj tego wzorca, gdy hostujesz kod agenta poza Foundry — potencjalnie osadzony w Twojej aplikacji — ale chcesz korzystać z funkcji agentów Foundry, takich jak modele i narzędzia platformy.

Wzorzec efemeryczny i hostowani agenci są dodatkiem, a nie alternatywami. Ten sam kod agenta w ramach Agent Framework można również spakować jako hostowanego agenta i udostępnić za pośrednictwem interfejsu API Foundry Agents — co jest przydatne, gdy chcesz mieć punkt końcowy zarządzany przez Foundry, który mogą wywoływać inne aplikacje, usługi lub agenci. Możesz wykonać obie czynności z jednej bazy kodu: uruchomić agenta w procesie, w którym jest dostarczany z aplikacją, i opublikować tę samą definicję co hostowany agent, w którym potrzebują go inni wywołujący.

Co punkt końcowy projektu Foundry dodaje do interfejsu API Responses OpenAI

Interfejs API Responses w punkcie końcowym projektu Foundry jest zgodny z interfejsem API Responses firmy OpenAI, więc istniejące klienty OpenAI współpracują z nim przy minimalnych zmianach. Punkt końcowy projektu Foundry dodatkowo obejmuje następujące elementy:

  • Dane w zakresie projektu: Pliki, magazyny wektorowe i inne dane są przechowywane na poziomie projektu, a nie na poziomie zasobów, co zapewnia izolację danych między projektami i umożliwia wykorzystanie własnych zasobów w ramach standardowej konfiguracji agenta.
  • Modele Foundry oprócz modeli OpenAI: Modele Foundry oferowane bezpośrednio przez platformę Azure (nie tylko modele OpenAI) są dostępne przez ten sam interfejs API.
  • Narzędzia specyficzne dla platformy Foundry: Narzędzia platformowe, takie jak SharePoint, WorkIQ i Fabric IQ, są dostępne obok standardowych narzędzi OpenAI.
  • Uwierzytelnianie typu on-behalf-of (OBO) dla narzędzi: Narzędzia mogą wywoływać usługi podrzędne w imieniu zalogowanego użytkownika, a nie tylko przy użyciu tożsamości aplikacji.
  • Obserwowalność i nadzór na poziomie projektu: Wywołania wykonywane za pośrednictwem punktu końcowego projektu przechodzą przez mechanizmy śledzenia, monitorowania, filtry treści i konfigurację tożsamości projektu bez potrzeby dodatkowej konfiguracji (zobacz Możliwości obserwowalności i funkcje dla przedsiębiorstw).

Wywoływanie punktu końcowego projektu — a nie punktu końcowego openAI na poziomie zasobu — jest tym, co umożliwia odblokowanie tych funkcji w zakresie projektu.

Wymagania wstępne

  • Zainstalowano środowisko Python w wersji 3.10 lub nowszej.

Ustawianie zmiennych środowiskowych

Zapisz punkt końcowy projektu i nazwę wdrożonego modelu jako zmienne środowiskowe. Poniższe przykłady odczytują te wartości ze środowiska.

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

Instalowanie pakietów

Zainstaluj pakiet Platformy agentów za pomocą dostawcy rozwiązania 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 udostępnia metodę rozszerzenia AsAIAgent(...) na AIProjectClient i przechodnio wprowadza Microsoft.Agents.AI.

Utwórz agenta

Utwórz efemerycznego agenta, który działa lokalnie w procesie i wywołuje interfejs API Odpowiedzi na potrzeby wnioskowania modelu i orkiestracji narzędzi.

Użyj FoundryChatClient i klasy 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())

Dane wyjściowe wyświetlają odpowiedź agenta. Ponieważ agent jest efemeryczny, żadna definicja nie jest utrwalana w usłudze — istnieje tylko przez okres istnienia procesu Python.

Użyj AIProjectClient.AsAIAgent(...) w Microsoft Agent Framework, aby opakować punkt końcowy projektu 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?")}");

Dane wyjściowe wyświetlają odpowiedź agenta. Ponieważ agent jest efemeryczny, żadna definicja nie jest utrwalana w usłudze — istnieje tylko przez okres istnienia procesu.

Dodaj narzędzia funkcji

Zdefiniuj lokalne narzędzia funkcji i przekaż je do agenta. Agent automatycznie wywołuje te narzędzia w razie potrzeby podczas konwersacji.

Zdefiniuj narzędzia funkcji lokalnych przy użyciu dekoratora @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 używa interfejsu API odpowiedzi, aby określić, kiedy wywołać get_weather funkcję, wykona ją lokalnie i zwraca wynik w języku naturalnym.

Zdefiniuj metodę lokalną, oznacz ją atrybutami [Description] i opakuj ją w 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 używa interfejsu Responses API do określenia, kiedy wywołać GetWeather, wykonuje to lokalnie i zwraca wynik w naturalnym języku.

Korzystanie z narzędzia wyszukiwania w Internecie

Interfejs API odpowiedzi w punkcie końcowym projektu Foundry udostępnia wbudowane narzędzia hostowane, takie jak wyszukiwanie w Internecie. Udziel agentowi dostępu do wyszukiwania w Internecie bez żadnej lokalnej implementacji.

Użyj 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())

Narzędzie do wyszukiwania w sieci działa po stronie serwera za pośrednictwem interfejsu API Responses projektu Foundry. Możesz połączyć to z lokalnymi narzędziami funkcji, aby zapewnić agentowi zarówno dostęp do internetu, jak i możliwość uruchamiania niestandardowego kodu:

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

Przekaż new HostedWebSearchTool() na liście 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?")}");

Narzędzie do wyszukiwania w internecie działa po stronie serwera za pośrednictwem interfejsu API Responses projektu Foundry. Możesz połączyć je z lokalnymi narzędziami funkcyjnymi, aby zapewnić agentowi zarówno dostęp do sieci, jak i możliwość uruchamiania niestandardowego kodu:

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

Strumieniowanie odpowiedzi

Odbieraj odpowiedzi podczas generowania zamiast czekać na pełną wiadomość.

Użyj parametru stream=True :

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

Wywołaj RunStreamingAsync i iteruj po strumieniu 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();

Dane wyjściowe przesyłania strumieniowego są wyświetlane przyrostowo w konsoli, ponieważ model generuje każdy token.

Obserwowalność i funkcje dla przedsiębiorstw

Tymczasowe nie oznacza niezarządzane. Ponieważ wywołania przechodzą przez punkt końcowy projektu, dziedziczą konfigurację przedsiębiorstwa projektu bez dodatkowego okablowania:

  • Śledzenie i monitorowanie: informacje o żądaniach, wywołaniach narzędzi i wykorzystaniu tokenów trafiają do mechanizmów observability w Foundry dla projektu.
  • Filtry i nadzór: filtry zawartości na poziomie Project i zasady odpowiedzialnej sztucznej inteligencji mają zastosowanie do każdego wywołania.
  • Tożsamość i dostęp: Wywołania są uwierzytelniane względem konfiguracji tożsamości projektu; narzędzia z obsługą OBO mogą działać w imieniu zalogowanego użytkownika.

Wzorzec efemeryczny nie jest wariantem o ograniczonych możliwościach — otrzymujesz te same modele Foundry, narzędzia, mechanizmy obserwowalności i nadzoru, niezależnie od tego, czy uruchamiasz agenta w procesie, czy opakowujesz ten sam kod jako agenta hostowanego. Wybór dotyczy kształtu wdrożenia, a nie zestawu funkcji.

Bezpośrednie używanie zestawu OpenAI SDK

Ponieważ interfejs Responses API projektu Foundry jest kompatybilny z OpenAI, można go również wywoływać bezpośrednio za pomocą pakietu OpenAI SDK, ustawiając w kliencie punkt końcowy projektu ({project_endpoint}/openai/v1/responses). Użyj tej ścieżki tylko wtedy, gdy masz już kod zestawu OpenAI SDK lub potrzebujesz kontroli niższego poziomu nad kształtami żądania i odpowiedzi. Nowy kod powinien w pierwszej kolejności korzystać z platformy Agent Framework, która obsługuje za Ciebie uwierzytelnianie, integrację narzędzi i orkiestrację.

Aby zapoznać się z przykładami zestawu SDK, zobacz:

Przykłady Foundry Responses (azure-ai-projects)

Przykłady Azure.AI.OpenAI

Uprzątnij zasoby

Ponieważ agenci utworzeni w ramach Agent Framework są tymczasowi, czyszczenie po stronie usługi nie jest konieczne. Agent istnieje tylko w Twoim lokalnym procesie. Jeśli utworzono zasoby usługi Foundry, które nie są już potrzebne, usuń je w portalu Foundry.

Treści powiązane

Szczegółowe informacje na temat tego wzorca

Spakuj ten sam kod agenta co hostowany agent

  • Last updated on