Partager via

points de terminaison compatibles avec « OpenAI »

Agent Framework prend en charge les protocoles compatibles OpenAI pour les deux agents d’hébergement derrière des API standard et la connexion à n’importe quel point de terminaison compatible OpenAI.

Qu’est-ce que les protocoles OpenAI ?

Deux protocoles OpenAI sont pris en charge :

  • API de complétions de chat — format standard de demande/réponse sans état pour les interactions de conversation
  • API Réponses : format avancé qui prend en charge les conversations, la diffusion en continu et les processus d’agent de longue durée

L’API Réponses est désormais l’approche par défaut et recommandée en fonction de la documentation d’OpenAI. Il fournit une interface plus complète et riche en fonctionnalités pour la création d’applications IA avec la gestion des conversations intégrée, les fonctionnalités de streaming et la prise en charge des processus de longue durée.

Utilisez l’API Réponses quand :

  • Création de nouvelles applications (valeur par défaut recommandée)
  • Vous avez besoin de la gestion des conversations côté serveur. Toutefois, ce n’est pas une exigence : vous pouvez toujours utiliser l’API Réponses en mode sans état.
  • Vous souhaitez un historique des conversations persistantes
  • Vous créez des processus d’agent de longue durée
  • Vous avez besoin de fonctionnalités de streaming avancées avec des types d’événements détaillés
  • Vous souhaitez suivre et gérer des réponses individuelles (par exemple, récupérer une réponse spécifique par ID, vérifier son état ou annuler une réponse en cours d’exécution)

Utilisez l'API Chat Completions lorsque :

  • Migration des applications existantes qui s’appuient sur le format Achèvements de conversation
  • Vous avez besoin d’interactions simples et sans état de requête/réponse
  • La gestion de l’état est entièrement gérée par votre client
  • Vous intégrez des outils existants qui prennent uniquement en charge les complétions de chat.
  • Vous avez besoin d’une compatibilité maximale avec les systèmes hérités

Hébergement d’agents en tant que points de terminaison OpenAI (.NET)

La bibliothèque Microsoft.Agents.AI.Hosting.OpenAI vous permet de rendre disponibles des agents IA via des points de terminaison HTTP compatibles OpenAI, en prenant en charge les API de complétude de chat et de réponses. Cela vous permet d’intégrer vos agents à n’importe quel client ou outil compatible OpenAI.

Package NuGet :

API de saisie semi-automatique de conversation

L'API de complétions de chat fournit une interface simple et sans état pour interagir avec les agents en utilisant le format de conversation standard d'OpenAI.

Configuration d’un agent dans ASP.NET Core avec l’intégration de ChatCompletions

Voici un exemple complet d’exposition d’un agent via l’API de terminaisons de chat :

Prerequisites

1. Créer un projet d’API web core ASP.NET

Créez un projet d’API web core ASP.NET ou utilisez-en un existant.

2. Installer les dépendances requises

Installez les packages suivants :

Exécutez les commandes suivantes dans votre répertoire de projet pour installer les packages NuGet requis :

# Hosting.A2A.AspNetCore for OpenAI ChatCompletions/Responses protocol(s) integration
dotnet add package Microsoft.Agents.AI.Hosting.OpenAI --prerelease

# Libraries to connect to Azure OpenAI
dotnet add package Azure.AI.OpenAI --prerelease
dotnet add package Azure.Identity
dotnet add package Microsoft.Extensions.AI
dotnet add package Microsoft.Extensions.AI.OpenAI --prerelease

# Swagger to test app
dotnet add package Microsoft.AspNetCore.OpenApi
dotnet add package Swashbuckle.AspNetCore

3. Configurer la connexion Azure OpenAI

L’application nécessite une connexion Azure OpenAI. Configurez le point de terminaison et le nom du déploiement à l'aide de dotnet user-secrets ou de variables d'environnement. Vous pouvez également simplement modifier le appsettings.json, mais ce n’est pas recommandé pour les applications déployées en production, car certaines données peuvent être considérées comme secrètes.

dotnet user-secrets set "AZURE_OPENAI_ENDPOINT" "https://<your-openai-resource>.openai.azure.com/"
dotnet user-secrets set "AZURE_OPENAI_DEPLOYMENT_NAME" "gpt-4o-mini"

4. Ajoutez le code à Program.cs

Remplacez le contenu de Program.cs par le code suivant :

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI.Hosting;
using Microsoft.Extensions.AI;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();
builder.Services.AddSwaggerGen();

string endpoint = builder.Configuration["AZURE_OPENAI_ENDPOINT"]
    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
string deploymentName = builder.Configuration["AZURE_OPENAI_DEPLOYMENT_NAME"]
    ?? throw new InvalidOperationException("AZURE_OPENAI_DEPLOYMENT_NAME is not set.");

// Register the chat client
IChatClient chatClient = new AzureOpenAIClient(
        new Uri(endpoint),
        new DefaultAzureCredential())
    .GetChatClient(deploymentName)
    .AsIChatClient();
builder.Services.AddSingleton(chatClient);

builder.AddOpenAIChatCompletions();

// Register an agent
var pirateAgent = builder.AddAIAgent("pirate", instructions: "You are a pirate. Speak like a pirate.");

var app = builder.Build();

app.MapOpenApi();
app.UseSwagger();
app.UseSwaggerUI();

// Expose the agent via OpenAI ChatCompletions protocol
app.MapOpenAIChatCompletions(pirateAgent);

app.Run();

Test du point de terminaison des complétions de chat

Une fois l’application en cours d’exécution, vous pouvez tester l’agent à l’aide du Kit de développement logiciel (SDK) OpenAI ou des requêtes HTTP :

Utilisation de la requête HTTP

POST {{baseAddress}}/pirate/v1/chat/completions
Content-Type: application/json
{
  "model": "pirate",
  "stream": false,
  "messages": [
    {
      "role": "user",
      "content": "Hey mate!"
    }
  ]
}

Remarque : Remplacez {{baseAddress}} par votre point de terminaison de serveur.

Voici un exemple de réponse :

{
	"id": "chatcmpl-nxAZsM6SNI2BRPMbzgjFyvWWULTFr",
	"object": "chat.completion",
	"created": 1762280028,
	"model": "gpt-5",
	"choices": [
		{
			"index": 0,
			"finish_reason": "stop",
			"message": {
				"role": "assistant",
				"content": "Ahoy there, matey! How be ye farin' on this fine day?"
			}
		}
	],
	"usage": {
		"completion_tokens": 18,
		"prompt_tokens": 22,
		"total_tokens": 40,
		"completion_tokens_details": {
			"accepted_prediction_tokens": 0,
			"audio_tokens": 0,
			"reasoning_tokens": 0,
			"rejected_prediction_tokens": 0
		},
		"prompt_tokens_details": {
			"audio_tokens": 0,
			"cached_tokens": 0
		}
	},
	"service_tier": "default"
}

La réponse inclut l’ID de message, le contenu et les statistiques d’utilisation.

Les complétions de chat prennent également en charge la diffusion en continu, avec une sortie retournée par blocs dès que le contenu est disponible. Cette fonctionnalité permet d’afficher progressivement la sortie. Vous pouvez activer la diffusion en continu en spécifiant "stream": true. Le format de sortie se compose de segments Server-Sent Events (SSE), comme défini dans la spécification OpenAI Chat Completions.

POST {{baseAddress}}/pirate/v1/chat/completions
Content-Type: application/json
{
  "model": "pirate",
  "stream": true,
  "messages": [
    {
      "role": "user",
      "content": "Hey mate!"
    }
  ]
}

Et la sortie que nous obtenons est un ensemble de blocs ChatCompletions :

data: {"id":"chatcmpl-xwKgBbFtSEQ3OtMf21ctMS2Q8lo93","choices":[],"object":"chat.completion.chunk","created":0,"model":"gpt-5"}

data: {"id":"chatcmpl-xwKgBbFtSEQ3OtMf21ctMS2Q8lo93","choices":[{"index":0,"finish_reason":"stop","delta":{"content":"","role":"assistant"}}],"object":"chat.completion.chunk","created":0,"model":"gpt-5"}

...

data: {"id":"chatcmpl-xwKgBbFtSEQ3OtMf21ctMS2Q8lo93","choices":[],"object":"chat.completion.chunk","created":0,"model":"gpt-5","usage":{"completion_tokens":34,"prompt_tokens":23,"total_tokens":57,"completion_tokens_details":{"accepted_prediction_tokens":0,"audio_tokens":0,"reasoning_tokens":0,"rejected_prediction_tokens":0},"prompt_tokens_details":{"audio_tokens":0,"cached_tokens":0}}}

La réponse de diffusion en continu contient des informations similaires, mais remises en tant qu’événements Server-Sent.

API Responses

L’API Réponses fournit des fonctionnalités avancées, notamment la gestion des conversations, la diffusion en continu et la prise en charge des processus d’agent de longue durée.

Configuration d’un agent dans ASP.NET Core avec l’intégration de l’API Réponses

Voici un exemple complet utilisant l’API Réponses :

Prerequisites

Suivez les mêmes prérequis que l'exemple de complétions de chat (étapes 1 à 3).

4. Ajoutez le code à Program.cs

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI.Hosting;
using Microsoft.Extensions.AI;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();
builder.Services.AddSwaggerGen();

string endpoint = builder.Configuration["AZURE_OPENAI_ENDPOINT"]
    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
string deploymentName = builder.Configuration["AZURE_OPENAI_DEPLOYMENT_NAME"]
    ?? throw new InvalidOperationException("AZURE_OPENAI_DEPLOYMENT_NAME is not set.");

// Register the chat client
IChatClient chatClient = new AzureOpenAIClient(
        new Uri(endpoint),
        new DefaultAzureCredential())
    .GetChatClient(deploymentName)
    .AsIChatClient();
builder.Services.AddSingleton(chatClient);

builder.AddOpenAIResponses();
builder.AddOpenAIConversations();

// Register an agent
var pirateAgent = builder.AddAIAgent("pirate", instructions: "You are a pirate. Speak like a pirate.");

var app = builder.Build();

app.MapOpenApi();
app.UseSwagger();
app.UseSwaggerUI();

// Expose the agent via OpenAI Responses protocol
app.MapOpenAIResponses(pirateAgent);
app.MapOpenAIConversations();

app.Run();

Test de l’API Réponses

L'API Réponses est similaire aux Complétions de chat, mais elle est stateful, ce qui vous permet de passer un paramètre conversation. Comme les complétions de chat, il prend en charge le stream paramètre, qui contrôle le format de sortie : une seule réponse JSON ou un flux d’événements. L’API Réponses définit ses propres types d’événements de diffusion en continu, notamment response.created, , response.output_item.addedresponse.output_item.done, response.completedet d’autres.

Créer une conversation et une réponse

Vous pouvez envoyer une demande de réponses directement, ou vous pouvez d’abord créer une conversation à l’aide de l’API Conversations, puis lier les demandes suivantes à cette conversation.

Pour commencer, créez une conversation :

POST http://localhost:5209/v1/conversations
Content-Type: application/json
{
  "items": [
    {
        "type": "message",
        "role": "user",
        "content": "Hello!"
      }
  ]
}

La réponse inclut l’ID de conversation :

{
  "id": "conv_E9Ma6nQpRzYxRHxRRqoOWWsDjZVyZfKxlHhfCf02Yxyy9N2y",
  "object": "conversation",
  "created_at": 1762881679,
  "metadata": {}
}

Ensuite, envoyez une demande et spécifiez le paramètre de conversation. (Pour recevoir la réponse en tant qu’événements de diffusion en continu, définissez "stream": true dans la requête.)

POST http://localhost:5209/pirate/v1/responses
Content-Type: application/json
{
  "stream": false,
  "conversation": "conv_E9Ma6nQpRzYxRHxRRqoOWWsDjZVyZfKxlHhfCf02Yxyy9N2y",
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": [
        {
            "type": "input_text",
            "text": "are you a feminist?"
        }
      ]
    }
  ]
}

L’agent retourne la réponse et enregistre les éléments de conversation dans le stockage pour une récupération ultérieure :

{
  "id": "resp_FP01K4bnMsyQydQhUpovK6ysJJroZMs1pnYCUvEqCZqGCkac",
  "conversation": "conv_E9Ma6nQpRzYxRHxRRqoOWWsDjZVyZfKxlHhfCf02Yxyy9N2y",
  "object": "response",
  "created_at": 1762881518,
  "status": "completed",
  "incomplete_details": null,
  "output": [
    {
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Arrr, matey! As a pirate, I be all about respect for the crew, no matter their gender! We sail these seas together, and every hand on deck be valuable. A true buccaneer knows that fairness and equality be what keeps the ship afloat. So, in me own way, I’d say I be supportin’ all hearty souls who seek what be right! What say ye?"
        }
      ],
      "type": "message",
      "status": "completed",
      "id": "msg_1FAQyZcWgsBdmgJgiXmDyavWimUs8irClHhfCf02Yxyy9N2y"
    }
  ],
  "usage": {
    "input_tokens": 26,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 85,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 111
  },
  "tool_choice": null,
  "temperature": 1,
  "top_p": 1  
}

La réponse inclut les identificateurs de conversation et de message, le contenu et les statistiques d’utilisation.

Pour récupérer les éléments de conversation, envoyez cette requête :

GET http://localhost:5209/v1/conversations/conv_E9Ma6nQpRzYxRHxRRqoOWWsDjZVyZfKxlHhfCf02Yxyy9N2y/items?include=string

Cette opération renvoie une réponse JSON contenant à la fois les messages d’entrée et de sortie :

{
  "object": "list",
  "data": [
    {
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Arrr, matey! As a pirate, I be all about respect for the crew, no matter their gender! We sail these seas together, and every hand on deck be valuable. A true buccaneer knows that fairness and equality be what keeps the ship afloat. So, in me own way, I’d say I be supportin’ all hearty souls who seek what be right! What say ye?",
          "annotations": [],
          "logprobs": []
        }
      ],
      "type": "message",
      "status": "completed",
      "id": "msg_1FAQyZcWgsBdmgJgiXmDyavWimUs8irClHhfCf02Yxyy9N2y"
    },
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "are you a feminist?"
        }
      ],
      "type": "message",
      "status": "completed",
      "id": "msg_iLVtSEJL0Nd2b3ayr9sJWeV9VyEASMlilHhfCf02Yxyy9N2y"
    }
  ],
  "first_id": "msg_1FAQyZcWgsBdmgJgiXmDyavWimUs8irClHhfCf02Yxyy9N2y",
  "last_id": "msg_lUpquo0Hisvo6cLdFXMKdYACqFRWcFDrlHhfCf02Yxyy9N2y",
  "has_more": false
}

Exposition de plusieurs agents

Vous pouvez exposer plusieurs agents simultanément à l’aide des deux protocoles :

var mathAgent = builder.AddAIAgent("math", instructions: "You are a math expert.");
var scienceAgent = builder.AddAIAgent("science", instructions: "You are a science expert.");

// Add both protocols
builder.AddOpenAIChatCompletions();
builder.AddOpenAIResponses();

var app = builder.Build();

// Expose both agents via Chat Completions
app.MapOpenAIChatCompletions(mathAgent);
app.MapOpenAIChatCompletions(scienceAgent);

// Expose both agents via Responses
app.MapOpenAIResponses(mathAgent);
app.MapOpenAIResponses(scienceAgent);

Les agents seront disponibles à l’adresse suivante :

  • Achèvements de conversation : /math/v1/chat/completions et /science/v1/chat/completions
  • Réponses : /math/v1/responses et /science/v1/responses

Points de terminaison personnalisés

Vous pouvez personnaliser les chemins d’accès du point de terminaison :

// Custom path for Chat Completions
app.MapOpenAIChatCompletions(mathAgent, path: "/api/chat");

// Custom path for Responses
app.MapOpenAIResponses(scienceAgent, responsesPath: "/api/responses");

Connexion à des points de terminaison OpenAI-Compatible (Python)

Python OpenAIChatClient et OpenAIResponsesClient prennent en charge un base_url paramètre, ce qui vous permet de vous connecter à n’importe quel point de terminaison compatible OpenAI, y compris les agents auto-hébergés, les serveurs d’inférence locaux (Ollama, LM Studio, vLLM) ou les API openAI tierces compatibles.

pip install agent-framework --pre

Client d'accomplissement des conversations

Utilisez OpenAIChatClient avec base_url pour pointer vers n’importe quel serveur compatible avec les Terminaisons de conversation.

import asyncio
from agent_framework import tool
from agent_framework.openai import OpenAIChatClient

@tool(approval_mode="never_require")
def get_weather(location: str) -> str:
    """Get the weather for a location."""
    return f"Weather in {location}: sunny, 22°C"

async def main():
    # Point to any OpenAI-compatible endpoint
    agent = OpenAIChatClient(
        base_url="http://localhost:11434/v1/",  # e.g. Ollama
        api_key="not-needed",                   # placeholder for local servers
        model_id="llama3.2",
    ).as_agent(
        name="WeatherAgent",
        instructions="You are a helpful weather assistant.",
        tools=get_weather,
    )

    response = await agent.run("What's the weather in Seattle?")
    print(response)

asyncio.run(main())

Réponses Client

Utilisez OpenAIResponsesClient avec base_url pour les points de terminaison qui prennent en charge l’API Réponses :

import asyncio
from agent_framework.openai import OpenAIResponsesClient

async def main():
    agent = OpenAIResponsesClient(
        base_url="https://your-hosted-agent.example.com/v1/",
        api_key="your-api-key",
        model_id="gpt-4o-mini",
    ).as_agent(
        name="Assistant",
        instructions="You are a helpful assistant.",
    )

    # Non-streaming
    response = await agent.run("Hello!")
    print(response)

    # Streaming
    async for chunk in agent.run("Tell me a joke", stream=True):
        if chunk.text:
            print(chunk.text, end="", flush=True)

asyncio.run(main())

Serveurs OpenAI-Compatible courants

L’approche base_url fonctionne avec n’importe quel serveur exposant le format OpenAI Chat Completions :

Serveur URL de base Remarques
Ollama http://localhost:11434/v1/ Inférence locale, aucune clé API n’est nécessaire
LM Studio http://localhost:1234/v1/ Inférence locale avec l’interface graphique utilisateur
vLLM http://localhost:8000/v1/ Service à débit élevé
Azure AI Foundry Votre point de terminaison de déploiement Utilise les informations d’identification Azure
Agents du cadre de l'agent hébergé Votre point de terminaison d’agent Agents .NET exposés via MapOpenAIChatCompletions

Note

Vous pouvez également définir la OPENAI_BASE_URL variable d’environnement au lieu de passer base_url directement. Le client l’utilisera automatiquement.

Utilisation des clients Azure OpenAI

Les variantes Azure OpenAI (AzureOpenAIChatClient, AzureOpenAIResponsesClient) se connectent aux points de terminaison Azure OpenAI avec les informations d'identification Azure, sans besoin de base_url.

from agent_framework.azure import AzureOpenAIResponsesClient

agent = AzureOpenAIResponsesClient().as_agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
)

Configurez avec des variables d’environnement :

export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
export AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME="gpt-4o-mini"

Voir aussi

Prochaines étapes

Portée

  • Last updated on