Démarrage rapide : Générer des agents à l’aide de l’API Réponses

Dans ce guide de démarrage rapide, vous appelez l’API Réponses sur un point de terminaison de projet Foundry à partir de votre propre code pour générer un agent éphémère , un agent dont la définition (instructions, outils, modèle) réside dans votre code d’application au lieu d’une ressource persistante dans le service De l’agent Foundry. Chaque appel construit l’agent dans votre processus et appelle l’API Réponses pour l’inférence de modèle et l’orchestration des outils.

Ce modèle convient aux développeurs, aux éditeurs de logiciels indépendants et aux acteurs du numérique qui souhaitent que leurs définitions d’agent soient incluses et versionnées avec le reste du code de leur application, plutôt que gérées comme une ressource distincte qu’une personne doit maintenir synchronisée avec l’application. Contrairement aux agents basés sur des invites, il n’existe aucune ressource d’agent à créer, mettre à jour ou supprimer dans Foundry — la gestion du cycle de vie est remplacée par des appels directs à l’API Responses.

L’API Réponses est le modèle unique et le point d’entrée des outils pour Foundry. Vous pouvez l’appeler sur deux points de terminaison différents :

  • Point de terminaison du projet Foundry (recommandé pour ce guide de démarrage rapide) — prise en charge complète de Foundry. Expose les modèles Foundry à partir des outils de catalogue et de plateforme (recherche de fichiers, interpréteur de code, mémoire, recherche web, MCP, SharePoint, WorkIQ, Fabric IQ, etc.) via une surface d’API à portée de projet unique, atteinte à {project_endpoint}/openai/v1/responses.
  • Azure point de terminaison OpenAI : meilleure latence et compatibilité maximale avec les clients OpenAI existants. Utilisez cette option lorsque vous avez uniquement besoin de modèles OpenAI et d’outils OpenAI standard et que vous n’avez pas besoin de fonctionnalités spécifiques à Foundry.

Le chemin recommandé est Agent Framework, qui gère l’authentification, le câblage des outils et l’orchestration des messages pour vous. Dans Python il s'agit FoundryChatClient ; dans .NET il s'agit AIProjectClient.AsAIAgent(...). Le Kit de développement logiciel (SDK) OpenAI fonctionne également sur ce point de terminaison et est couvert comme alternative dans l’utilisation directe du KIT DE développement logiciel (SDK) OpenAI.

Si vous n’avez pas d’abonnement Azure, créez un compte gratuit.

Quand utiliser le modèle d’agent éphémère

Utilisez ce modèle lorsque vous hébergez du code d’agent en dehors de Foundry , potentiellement incorporé dans votre propre application, mais que vous souhaitez accéder aux fonctionnalités de l’agent Foundry, telles que les modèles et les outils de plateforme.

Le modèle éphémère et les agents hébergés sont additifs, et non des alternatives. Le même code d’agent Agent Framework peut également être empaqueté en tant qu’agent hébergé et exposé par le biais de l’API Agents Foundry , utile lorsque vous souhaitez un point de terminaison géré par Foundry que d’autres applications, services ou agents peuvent appeler. Vous pouvez effectuer les deux à partir d’une base de code : exécutez l’agent in-process où il est fourni avec votre application et publiez la même définition qu’un agent hébergé où d’autres appelants en ont besoin.

Ce qu’ajoute le point de terminaison du projet Foundry à l’API Responses d’OpenAI

L’API Responses sur le point de terminaison d’un projet Foundry est compatible avec l’API OpenAI Responses, de sorte que les clients OpenAI existants peuvent fonctionner moyennant un minimum de modifications. Le point de terminaison du projet Foundry ajoute ce qui suit en haut :

  • Données délimitées au projet : les fichiers, les magasins vectoriels et d’autres données sont stockés au niveau du projet plutôt qu’au niveau de la ressource, ce qui assure une isolation des données par projet et vous permet d’utiliser vos propres ressources grâce à la configuration standard de l’agent.
  • Foundry Models en plus d’OpenAI : Foundry Models vendu directement par Azure (pas seulement les modèles OpenAI) sont disponibles via la même API.
  • Outils spécifiques à Foundry : des outils de plateforme tels que SharePoint, WorkIQ et Fabric IQ sont disponibles en complément des outils OpenAI standard.
  • Authentification au nom de l’utilisateur (OBO) pour les outils : les outils peuvent appeler des services en aval en tant qu’utilisateur connecté, pas seulement comme identité d’application.
  • Observabilité et gouvernance au niveau du projet : les appels effectués via le point de terminaison du projet passent par le traçage, la surveillance, les filtres de contenu et la configuration de l’identité du projet sans configuration supplémentaire (voir Observabilité et fonctionnalités d’entreprise).

L’appel du point de terminaison du projet , et non pas un point de terminaison OpenAI au niveau de la ressource, est ce qui déverrouille ces fonctionnalités délimitées au projet.

Prerequisites

  • Python 3.10 ou version ultérieure installée.

Définir des variables d’environnement

Stockez votre point de terminaison de projet et le nom du modèle déployé en tant que variables d’environnement. Les exemples ci-dessous lisent ces valeurs à partir de l’environnement.

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

Installer des packages

Installez le package Agent Framework avec le fournisseur 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 fournit la méthode d’extension AsAIAgent(...) sur AIProjectClient et apporte de manière transitive Microsoft.Agents.AI.

Créer un agent

Créez un agent éphémère qui s’exécute localement dans votre processus et appelle l’API Réponses pour l’inférence de modèle et l’orchestration des outils.

Utilisez FoundryChatClient et la Agent classe.

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

La sortie affiche la réponse de l’agent. Étant donné que l’agent est éphémère, aucune définition n’est conservée dans le service , elle n’existe que pour la durée de vie du processus de Python.

Utilisez AIProjectClient.AsAIAgent(...) à partir de Microsoft Agent Framework pour encapsuler le point de terminaison du projet Foundry en tant que 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?")}");

La sortie affiche la réponse de l’agent. Étant donné que l’agent est éphémère, aucune définition n’est conservée dans le service . Elle n’existe que pour la durée de vie du processus.

Ajouter des outils de fonction

Définissez les outils de fonction local et transmettez-les à l’agent. L’agent appelle automatiquement ces outils si nécessaire pendant une conversation.

Définissez des outils de fonction locaux à l’aide du décorateur @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())

L’agent utilise l’API Réponses pour déterminer quand appeler la get_weather fonction, l’exécuter localement et retourne le résultat en langage naturel.

Définissez une méthode locale, décorez-la avec [Description] des attributs et encapsulez-la avec 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?")}");

L’agent utilise l’API Réponses pour déterminer quand appeler GetWeather, l’exécute localement et retourne le résultat en langage naturel.

Utiliser l’outil de recherche web

L’API Réponses sur le point de terminaison du projet Foundry fournit des outils hébergés intégrés comme la recherche web. Donnez à votre agent l’accès à la recherche web sans implémentation locale.

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

L’outil de recherche web exécute côté serveur via l’API Réponses du projet Foundry. Vous pouvez la combiner avec des outils de fonction locaux pour donner à votre agent un accès web et des fonctionnalités de code personnalisées :

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

Passez new HostedWebSearchTool() dans la liste 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?")}");

L’outil de recherche web exécute côté serveur via l’API Réponses du projet Foundry. Vous pouvez la combiner avec des outils de fonction locaux pour donner à votre agent un accès web et des fonctionnalités de code personnalisées :

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

Diffuser des réponses

Recevez les réponses au fur et à mesure qu’elles génèrent au lieu d’attendre le message complet.

Utilisez le stream=True paramètre :

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

Appelez RunStreamingAsync et itérer le flux 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();

La sortie en continu s’affiche progressivement dans la console à mesure que le modèle génère chaque jeton.

Observabilité et capacités d’entreprise

Éphémère ne signifie pas non géré. Étant donné que les appels passent par le point de terminaison du projet, ils héritent de la configuration d’entreprise du projet sans câblage supplémentaire :

  • Suivi et surveillance : demandes, appels d’outils et flux d’utilisation des jetons dans l’observabilité Foundry pour le projet.
  • Filtres de contenu et gouvernance : les filtres de contenu au niveau du projet et les stratégies d’IA responsable s’appliquent à chaque appel.
  • Identité et accès : les appels s’authentifient sur la configuration de l’identité du projet ; Les outils compatibles avec OBO peuvent agir en tant qu’utilisateur connecté.

L’approche éphémère n’est pas un niveau aux capacités réduites — vous bénéficiez des mêmes modèles Foundry, outils, capacités d’observabilité et mécanismes de gouvernance, que vous exécutiez l’agent dans le processus ou packagiez le même code sous forme d’agent hébergé. Le choix concerne la forme de déploiement, et non l’ensemble de fonctionnalités.

Utiliser directement le Kit de développement logiciel (SDK) OpenAI

Étant donné que l’API Réponses du projet Foundry est compatible Avec OpenAI, vous pouvez également l’appeler directement à partir du Kit de développement logiciel (SDK) OpenAI en pointant le client sur le point de terminaison du projet ({project_endpoint}/openai/v1/responses). Utilisez ce chemin uniquement si vous avez déjà du code du KIT SDK OpenAI ou si vous avez besoin d’un contrôle de niveau inférieur sur les formes de requête et de réponse. Le nouveau code doit utiliser de préférence l’Agent Framework, qui prend en charge l’authentification, l’intégration des outils et l’orchestration pour vous.

Pour obtenir des exemples de sdk, consultez :

Exemples de Foundry Responses (azure-ai-projects)

Exemples Azure.AI.OpenAI

Nettoyer les ressources

Étant donné que les agents Agent Framework créés ici sont éphémères, aucun nettoyage côté service n’est nécessaire. L’agent existe uniquement dans votre processus local. Si vous avez créé des ressources Foundry dont vous n’avez plus besoin, supprimez-les dans le portail Foundry.

Contenu connexe

Aller plus loin sur ce modèle

Empaqueter le même code d’agent qu’un agent hébergé

  • Last updated on