Quickstart: Agents bouwen met behulp van de Antwoorden-API

In deze quickstart roept u de Antwoorden-API aan op een Foundry-projecteindpunt vanuit uw eigen code om een tijdelijke agent te bouwen, een agent waarvan de definitie (instructies, hulpprogramma's, model) zich in uw toepassingscode bevindt in plaats van als een persistente resource in Foundry Agent Service. Elke aanroep maakt de agent in uw proces en roept de Antwoorden-API aan voor modeldeductie en indeling van hulpprogramma's.

Dit patroon past bij ontwikkelaars, ISV's en digital natives die willen dat hun agentdefinities samen met de rest van hun applicatiecode worden geleverd en geversioneerd, in plaats van als een losstaande resource die iemand synchroon moet houden met de app. In tegenstelling tot promptagenten is er geen agentresource om in Foundry te maken, bij te werken of te verwijderen. Levenscyclusbeheer wordt vervangen door de antwoorden-API rechtstreeks aan te roepen.

De Antwoorden-API is het toegangspunt voor één model en hulpprogramma's voor Foundry. U kunt deze aanroepen op twee verschillende eindpunten:

  • Foundry-projecteindpunt (deze quickstart, aanbevolen) - volledige Foundry-ondersteuning. Maakt Foundry-modellen beschikbaar vanuit de catalogus- en platformhulpprogramma's (bestandszoekopdrachten, code-interpreter, geheugen, webzoekopdrachten, MCP, SharePoint, WorkIQ, Fabric IQ en meer) via één api-oppervlak met projectbereik, bereikt op {project_endpoint}/openai/v1/responses.
  • Azure OpenAI-eindpunt — beste latentie en maximale compatibiliteit met bestaande OpenAI-clients. Gebruik dit als u alleen OpenAI-modellen en standaard OpenAI-hulpprogramma's nodig hebt en geen Foundry-specifieke mogelijkheden nodig hebt.

Het aanbevolen pad is het Agent Framework, dat verificatie, bedrading van hulpprogramma's en berichtindeling voor u afhandelt. In Python is dit FoundryChatClient; in .NET het AIProjectClient.AsAIAgent(...). De OpenAI SDK werkt ook op dit eindpunt en wordt behandeld als alternatief in De OpenAI SDK rechtstreeks gebruiken.

Als u geen Azure-abonnement hebt, maakt u een gratis account.

Wanneer gebruikt u het tijdelijke agentpatroon

Gebruik dit patroon wanneer u agentcode buiten Foundry host , mogelijk ingesloten in uw eigen toepassing, maar toegang wilt krijgen tot Foundry-agentfuncties zoals modellen en platformhulpprogramma's.

Het tijdelijke patroon en gehoste agents zijn additief, geen alternatieven. Dezelfde Agent Framework-agentcode kan ook worden verpakt als een gehoste agent en beschikbaar gemaakt via de Foundry Agents-API. Dit is handig wanneer u een door Foundry beheerd eindpunt wilt dat andere apps, services of agents kunnen aanroepen. U kunt beide doen vanuit één codebasis: voer de agent in het proces uit waar deze wordt geleverd met uw app en publiceer dezelfde definitie als een gehoste agent waar andere bellers deze nodig hebben.

Wat het Foundry-projecteindpunt toevoegt boven op de OpenAI-antwoorden-API

De Antwoorden-API op een Foundry-projecteindpunt is compatibel met de OpenAI-antwoorden-API, zodat bestaande OpenAI-clients ermee werken met minimale wijzigingen. Het Foundry-projecteindpunt voegt het volgende toe:

  • Gegevens op projectniveau: Bestanden, vectoropslag en andere gegevens worden op projectniveau opgeslagen in plaats van op resourceniveau, wat gegevensisolatie per project mogelijk maakt en u in staat stelt eigen resources te gebruiken via de standaardconfiguratie van de agent.
  • Foundry Models naast OpenAI: Foundry Models die rechtstreeks worden verkocht door Azure (niet alleen OpenAI-modellen) zijn beschikbaar via dezelfde API.
  • Foundry-specifieke hulpprogramma's: Platformhulpprogramma's zoals SharePoint, WorkIQ en Fabric IQ zijn beschikbaar naast de standaard OpenAI-hulpprogramma's.
  • On-behalf-of-authenticatie (OBO) voor tools: Tools kunnen downstreamservices aanroepen namens de aangemelde gebruiker, niet alleen met de identiteit van de toepassing.
  • Observability op projectniveau en governance: Aanroepen die via het projecteindpunt worden gedaan, maken zonder extra configuratie gebruik van de tracering, bewaking, inhoudsfilters en identiteitsconfiguratie van het project (zie Observability en enterprise-mogelijkheden).

Het aanroepen van het projecteindpunt ( niet een OpenAI-eindpunt op resourceniveau) is wat deze mogelijkheden binnen het projectbereik ontgrendelt.

Prerequisites

  • Python 3.10 of hoger geïnstalleerd.

Omgevingsvariabelen instellen

Sla uw projecteindpunt en de naam van het geïmplementeerde model op als omgevingsvariabelen. In de onderstaande voorbeelden worden deze waarden uit de omgeving gelezen.

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

Pakketten installeren

Installeer het Agent Framework-pakket met de Foundry-provider:

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 biedt de extensiemethode AsAIAgent(...) op AIProjectClient en haalt transitief Microsoft.Agents.AI binnen.

Een agent maken

Maak een tijdelijke agent die lokaal wordt uitgevoerd in uw proces en roept de Response-API aan voor modeldeductie en indeling van hulpprogramma's.

Gebruik FoundryChatClient en de 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())

De uitvoer toont het antwoord van de agent. Omdat de agent kortstondig is, blijft er geen definitie behouden voor de service. Deze bestaat alleen voor de levensduur van het Python proces.

Gebruik AIProjectClient.AsAIAgent(...) van het Microsoft Agent Framework om het Foundry-projecteindpunt te verpakken als een 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?")}");

De uitvoer toont het antwoord van de agent. Omdat de agent kortstondig is, wordt er geen definitie bewaard voor de service. Deze bestaat alleen voor de levensduur van het proces.

Functiehulpprogramma's toevoegen

Definieer lokale functiehulpprogramma's en geef deze door aan de agent. De agent roept deze hulpprogramma's automatisch aan wanneer dat nodig is tijdens een gesprek.

Definieer lokale functiehulpprogramma's met behulp van de @tool decorator.

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

De agent gebruikt de Antwoorden-API om te bepalen wanneer de get_weather functie moet worden aangeroepen, deze lokaal uit te voeren en het resultaat in natuurlijke taal te retourneren.

Definieer een lokale methode, verfraaid deze met [Description] kenmerken en verpakt deze met 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?")}");

De agent gebruikt de Responses API om te bepalen wanneer GetWeather moet worden aangeroepen, voert deze lokaal uit en retourneert het resultaat in natuurlijke taal.

Het webzoekprogramma gebruiken

De Antwoorden-API op het Eindpunt van het Foundry-project biedt ingebouwde, gehoste hulpprogramma's zoals zoeken op internet. Geef uw agent toegang tot webzoekopdrachten zonder lokale implementatie.

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

De webzoektool wordt aan de serverzijde uitgevoerd via de Responses API van het Foundry-project. U kunt deze combineren met lokale functiehulpprogramma's om uw agent zowel webtoegang als aangepaste codemogelijkheden te bieden:

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

Geef new HostedWebSearchTool() door in de tools-lijst:

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

De webzoektool wordt aan de serverzijde uitgevoerd via de Responses API van het Foundry-project. U kunt deze combineren met lokale functiehulpprogramma's om uw agent zowel webtoegang als aangepaste codemogelijkheden te bieden:

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

Antwoorden streamen

Ontvang antwoorden terwijl ze worden gegenereerd in plaats van te wachten op het volledige bericht.

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

Roep RunStreamingAsync aan en itereer over de stream 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();

Streaming-uitvoer wordt incrementeel weergegeven in de console wanneer elk token wordt gegenereerd door het model.

Waarneembaarheid en bedrijfsmogelijkheden

Kortstondig betekent niet onbeheerd. Omdat aanroepen het projecteindpunt doorlopen, nemen ze de bedrijfsconfiguratie van het project over zonder extra bedrading:

  • Tracering en monitoring: Verzoeken, toolaanroepen en tokengebruik worden doorgestuurd naar Foundry Observability voor het project.
  • Content-filters en -governance: inhoudsfilters op Project niveau en verantwoordelijk AI-beleid zijn van toepassing op elke aanroep.
  • Identiteit en toegang: roept verificatie aan op basis van de identiteitsconfiguratie van het project; Hulpprogramma's met OBO kunnen fungeren als de aangemelde gebruiker.

Het tijdelijke patroon is geen laag met beperkte mogelijkheden. U krijgt dezelfde Foundry-modellen, hulpprogramma's, waarneembaarheid en governance, ongeacht of u de agent in proces uitvoert of dezelfde code als een gehoste agent verpakt. De keuze betreft de implementatievorm, niet de beschikbare functionaliteiten.

De OpenAI SDK rechtstreeks gebruiken

Omdat de Foundry project Responses-API openAI-compatibel is, kunt u deze ook rechtstreeks vanuit de OpenAI SDK aanroepen door de client aan te wijzen op het projecteindpunt ({project_endpoint}/openai/v1/responses). Gebruik dit pad alleen als u al OpenAI SDK-code hebt of controle op een lager niveau nodig hebt over de aanvraag- en antwoordshapes. Nieuwe code moet de voorkeur geven aan het Agent Framework, dat verificatie, bedrading van hulpprogramma's en indeling voor u afhandelt.

Zie voor SDK-voorbeelden:

Voorbeelden van Foundry Responses (azure-ai-projects)

Azure. AI. OpenAI-voorbeelden

De hulpbronnen opschonen

Omdat Agent Framework-agents die hier zijn gemaakt kortstondig zijn, is er geen opschoning aan de servicezijde nodig. De agent bestaat alleen in uw lokale proces. Als u Foundry-resources hebt gemaakt die u niet meer nodig hebt, verwijdert u deze in de Foundry-portal.

Verwante inhoud

Ga dieper in op dit patroon

Dezelfde agentcode verpakken als een gehoste agent

  • Last updated on