Snabbstart: Skapa agenter med svars-API:et

I den här snabbstarten anropar du svars-API :et på en Foundry-projektslutpunkt från din egen kod för att skapa en tillfällig agent – en agent vars definition (instruktioner, verktyg, modell) finns i programkoden i stället för som en bevarad resurs i Foundry Agent Service. Varje anrop konstruerar agenten i din process och anropar svars-API:et för modellinferens och verktygsorkestrering.

Det här mönstret passar utvecklare, ISV:er och digitala infödingar som vill att deras agentdefinitioner ska levereras och versioneras med resten av programkoden, i stället för som en out-of-band-resurs som någon måste synkronisera med appen. Till skillnad från promptagenter finns det ingen agentresurs att skapa, uppdatera eller ta bort i Foundry – livscykelhanteringen ersätts genom att anropa svars-API:et direkt.

Responses API är den enda ingången för modeller och verktyg i Foundry. Du kan anropa den på två olika ändpunkter:

• Slutpunkt för Foundry-projekt (den här snabbstarten rekommenderas) – fullständigt Foundry-stöd. Exponerar Foundry-modeller från katalog- och plattformsverktygen (filsökning, kodtolk, minne, webbsökning, MCP, SharePoint, WorkIQ, Fabric IQ med mera) via en enda API-yta med projektomfattning som nås på {project_endpoint}/openai/v1/responses.
• Azure OpenAI-slutpunkt – bästa svarstid och maximal kompatibilitet med befintliga OpenAI-klienter. Använd detta när du bara behöver OpenAI-modeller och OpenAI-standardverktyg och inte behöver Foundry-specifika funktioner.

Den rekommenderade sökvägen är Agent Framework, som hanterar autentisering, verktygskopplingar och meddelandeorkestrering åt dig. I Python är detta FoundryChatClient. I .NET är det AIProjectClient.AsAIAgent(...). OpenAI SDK fungerar också mot den här slutpunkten och beskrivs som ett alternativ i Använd OpenAI SDK direkt.

Om du inte har någon Azure-prenumeration kan du skapa ett kostnadsfritt konto.

När du ska använda det tillfälliga agentmönstret

Använd det här mönstret när du är värd för agentkod utanför Foundry – potentiellt inbäddat i ditt eget program – men vill komma åt Foundry-agentfunktioner som modeller och plattformsverktyg.

Det tillfälliga mönstret och värdbaserade agenter är additiva, inte alternativ. Samma Agent Framework-agentkod kan också paketeras som en värdbaserad agent och exponeras via API:et Foundry Agents – användbart när du vill ha en Foundry-hanterad slutpunkt som andra appar, tjänster eller agenter kan anropa. Du kan göra båda från samma kodbas: köra agenten i processen där den levereras tillsammans med din app, och publicera samma definition som en hostad agent där andra anropare behöver den.

Vad Foundry-projektets slutpunkt tillför utöver OpenAI Responses API

Svars-API:et på en Foundry-projektslutpunkt är kompatibelt med OpenAI-svars-API:et, så befintliga OpenAI-klienter arbetar mot det med minimala ändringar. Slutpunkten för Foundry-projektet lägger till följande överst:

• Project-scoped data: Filer, vektorlager och andra data lagras på project nivå i stället för resursnivån, vilket ger dataisolering per project och låter dig använda bring-your-own-resurser via standardagentkonfiguration.
• Foundry Models utöver OpenAI: Foundry-modeller som säljs direkt av Azure (inte bara OpenAI-modeller) är tillgängliga via samma API.
• Foundry-specifika verktyg: Plattformsverktyg som SharePoint, WorkIQ och Fabric IQ är tillgängliga tillsammans med standardverktygen för OpenAI.
• OBO-autentisering för verktyg: Verktyg kan anropa underordnade tjänster som den inloggade användaren, inte bara som programidentitet.
• Observerbarhet och styrning på projektnivå: Anrop som görs via projektets slutpunkt går via projektets spårning, övervakning, innehållsfilter och identitetskonfiguration utan extra konfiguration (se Observerbarhet och företagsfunktioner).

Att anropa projektslutpunkten – inte en OpenAI-slutpunkt på resursnivå – är det som låser upp dessa projektomfattningsfunktioner.

Förutsättningar

• En modell som distribueras i Microsoft Foundry. Om du inte har någon modell slutför du först Quickstart: Konfigurera Microsoft Foundry-resurser.
• Azure CLI installerat och loggat in (az login).

• Python 3.10 eller senare installerat.

• .NET 8 SDK eller senare installerat.

Ange miljövariabler

Lagra projektslutpunkten och det distribuerade modellnamnet som miljövariabler. Exemplen nedan läser dessa värden från miljön.

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

Installera paket

Installera Agent Framework-paketet med Foundry-providern:

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 tillhandahåller tilläggsmetoden AsAIAgent(...) på AIProjectClient och transitivt tar in Microsoft.Agents.AI.

Skapa en handläggare

Skapa en tillfällig agent som körs lokalt i din process och anropar Svars-API:et för modellinferens och verktygsorkestrering.

Använd FoundryChatClient och Agent klassen.

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

Utdata skriver ut agentens svar. Eftersom agenten är kortlivad sparas ingen definition i tjänsten – den existerar bara under Python-processens livstid.

Använd AIProjectClient.AsAIAgent(...) från Microsoft Agent Framework för att omsluta Foundry-projektslutpunkten som en 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?")}");

Utdata skriver ut agentens svar. Eftersom agenten är tillfällig sparas ingen definition till tjänsten – den finns bara under hela processen.

Lägg till funktionsverktyg

Definiera lokala funktionsverktyg och skicka dem till agenten. Agenten anropar automatiskt dessa verktyg när det behövs under en konversation.

Definiera lokala funktionsverktyg med hjälp av dekoratören @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())

Agenten använder API:et Svar för att avgöra när funktionen ska anropas get_weather , körs lokalt och returnerar resultatet på naturligt språk.

Definiera en lokal metod, dekorera den med [Description] attribut och omslut den med 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?")}");

Agenten använder API:et Svar för att avgöra när det ska anropa GetWeather, kör det lokalt och returnerar resultatet på naturligt språk.

Använda webbsökningsverktyget

Svars-API:et på foundry-projektslutpunkten innehåller inbyggda värdbaserade verktyg som webbsökning. Ge din agent åtkomst till webbsökning utan någon lokal implementering.

Använd 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())

Webbsökningsverktyget kör serversidan via Foundry-projektets svars-API. Du kan kombinera den med lokala funktionsverktyg för att ge din agent både webbåtkomst och anpassade kodfunktioner:

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

Skicka new HostedWebSearchTool() i tools listan:

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

Webbsökningsverktyget kör serversidan via Foundry-projektets svars-API. Du kan kombinera den med lokala funktionsverktyg för att ge din agent både webbåtkomst och anpassade kodfunktioner:

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

Strömmande svar

Ta emot svar när de genererar i stället för att vänta på det fullständiga meddelandet.

Använd parametern 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())

Anropa RunStreamingAsync och iterera AgentResponseUpdate strömmen:

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

Strömmande utdata visas stegvis i konsolen när modellen genererar varje token.

Observerbarhets- och företagsfunktioner

Ephemeral betyder inte ohanterat. Eftersom anrop går via projektslutpunkten ärver de projektets företagskonfiguration utan extra ledningar:

• Spårning och övervakning: Begäranden, verktygsanrop och tokenanvändning flödar till Foundrys observabilitet för projektet.
• Innehållsfilter och styrning: innehållsfilter på Project nivå och ansvarsfulla AI-principer gäller för varje anrop.
• Identitet och åtkomst: Anrop autentiseras mot projektets identitetskonfiguration; OBO-aktiverade verktyg kan agera som den inloggade användaren.

Det tillfälliga mönstret är inte en nivå med reducerad kapacitet – du får samma Foundry-modeller, verktyg, observerbarhet och styrning oavsett om du kör agenten i processen eller paketera samma kod som en värdbaserad agent. Valet handlar om distributionsformen, inte funktionsuppsättningen.

Använd OpenAI SDK direkt

Eftersom Foundry-projektets svars-API är OpenAI-kompatibelt kan du även anropa det direkt från OpenAI SDK genom att peka klienten på projektslutpunkten ({project_endpoint}/openai/v1/responses). Använd endast den här sökvägen om du redan har OpenAI SDK-kod eller behöver kontroll på lägre nivå över formerna för begäran och svar. Ny kod bör föredra Agent Framework, som hanterar autentisering, verktygskopplingar och orkestrering åt dig.

För SDK-exempel, se:

Exempel på Foundry-svar (azure-ai-projects)

Azure. AI. OpenAI-exempel

Rensa resurser

Eftersom Agent Framework-agenter som skapas här är tillfälliga behövs ingen rensning på tjänstsidan. Agenten finns bara i din lokala process. Om du har skapat Foundry-resurser som du inte längre behöver tar du bort dem i Foundry-portalen.

Relaterat innehåll

Gå djupare på det här mönstret

• Agent Framework på GitHub

• Exempel för Foundry-provider (Python)
• Exempel på Responses API för Foundry-projekt (OpenAI SDK)

• Agenter med exempel i Foundry (.NET)

Paketera samma agentkod som en värdbaserad agent

• Snabbstart: Distribuera din första värdbaserade agent
• Snabbstart: Skapa en promptagent
• Vad är Foundry Agent Service?