Compartilhar via

Pontos de extremidade compatíveis com OpenAI

O Agent Framework dá suporte a protocolos compatíveis com OpenAI para hospedar agentes por trás de APIs padrão e conectar-se a qualquer ponto de extremidade compatível com OpenAI.

O que são protocolos OpenAI?

Há suporte para dois protocolos OpenAI:

  • API de Conclusões de Chat — Formato de solicitação/resposta sem estado padrão para interações de chat
  • API de respostas – formato avançado que dá suporte a conversas, streaming e processos de agente de execução longa

A API de Respostas agora é a abordagem padrão e recomendada de acordo com a documentação do OpenAI. Ele fornece uma interface mais abrangente e rica em recursos para a criação de aplicativos de IA com gerenciamento de conversa interno, recursos de streaming e suporte para processos de longa execução.

Use a API de Respostas quando:

  • Criando novos aplicativos (padrão recomendado)
  • Você precisa de gerenciamento de conversa do lado do servidor. No entanto, isso não é um requisito: você ainda pode usar a API de Respostas no modo sem estado.
  • Você deseja um histórico de conversa persistente
  • Você está criando processos de agente de longa duração
  • Você precisa de recursos avançados de streaming com tipos de eventos detalhados
  • Você deseja acompanhar e gerenciar respostas individuais (por exemplo, recuperar uma resposta específica por ID, verificar seu status ou cancelar uma resposta em execução)

Use a API de Conclusões de Chat quando:

  • Migrando aplicativos existentes que dependem do formato de Conclusões de Chat
  • Você precisa de interações de solicitação/resposta simples e sem estado
  • O gerenciamento de estado é tratado inteiramente pelo seu cliente
  • Você está fazendo integração com ferramentas existentes que dão suporte apenas a Completações de Chat.
  • Você precisa de compatibilidade máxima com sistemas herdados

Hospedagem de Agentes como Endpoints da OpenAI (.NET)

A biblioteca Microsoft.Agents.AI.Hosting.OpenAI permite que você exponha agentes de IA por meio de endpoints HTTP compatíveis com OpenAI, oferecendo suporte às APIs de Conclusões de Bate-papo e Respostas. Isso permite que você integre seus agentes a qualquer cliente ou ferramenta compatível com OpenAI.

Pacote NuGet:

API de conclusões de chat

A API de Conclusão de Conversas fornece uma interface simples e sem estado para interagir com agentes usando o formato de chat OpenAI padrão.

Configurando um agente no ASP.NET Core com a integração do ChatCompletions

Aqui está um exemplo completo expondo um agente por meio da API de Conclusões de Chat:

Pré-requisitos

1. Criar um projeto de API Web do ASP.NET Core

Crie um novo projeto de API Web do ASP.NET Core ou use um existente.

2. Instalar dependências necessárias

Instale os seguintes pacotes:

Execute os seguintes comandos no diretório do projeto para instalar os pacotes NuGet necessários:

# 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. Configurar a conexão do Azure OpenAI

O aplicativo requer uma conexão Azure OpenAI. Configure o endpoint e o nome da implantação usando dotnet user-secrets ou variáveis de ambiente. Você também pode simplesmente editar o appsettings.json, mas isso não é recomendado para os aplicativos implantados em produção, pois alguns dos dados podem ser considerados secretos.

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. Adicionar o código ao Program.cs

Substitua o conteúdo de Program.cs pelo seguinte código:

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

Testando o endpoint de conclusões de chat

Depois que o aplicativo estiver em execução, você poderá testar o agente usando o SDK do OpenAI ou solicitações HTTP:

Usando a solicitação HTTP

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

Observação: substitua {{baseAddress}} por seu endpoint de servidor.

Aqui está uma resposta de exemplo:

{
	"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"
}

A resposta inclui a ID da mensagem, o conteúdo e as estatísticas de uso.

O Chat Completions também dá suporte ao streaming, em que a saída é retornada em partes assim que o conteúdo estiver disponível. Essa funcionalidade permite exibir a saída progressivamente. Você pode habilitar o streaming especificando "stream": true. O formato de saída consiste em partes de Server-Sent Events (SSE), conforme definido na especificação de Conclusões de Chat da OpenAI.

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

E a saída que obtemos é um conjunto de blocos de 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}}}

A resposta de streaming contém informações semelhantes, mas entregues como Eventos Enviados pelo Servidor.

API de Respostas

A API de Respostas fornece recursos avançados, incluindo gerenciamento de conversa, streaming e suporte para processos de agente de longa execução.

Configurando um agente no ASP.NET Core com a integração da API de Respostas

Aqui está um exemplo completo usando a API de Respostas:

Pré-requisitos

Siga os mesmos pré-requisitos que o exemplo de Conclusões de Chat (etapas 1 a 3).

4. Adicionar o código ao 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();

Testando a API de Respostas

A API de Respostas é semelhante à de Conclusões de Chat, mas é com estado, permitindo que você passe um parâmetro conversation. Assim como o Chat Completions, ele dá suporte ao stream parâmetro, que controla o formato de saída: uma única resposta JSON ou um fluxo de eventos. A API de Respostas define seus próprios tipos de evento de streaming, incluindo response.created, response.output_item.addedresponse.output_item.done e response.completed e outros.

Criar uma conversa e resposta

Você pode enviar uma solicitação de Respostas diretamente ou, primeiro, criar uma conversa usando a API de Conversas e, em seguida, vincular solicitações subsequentes a essa conversa.

Para começar, crie uma nova conversa:

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

A resposta inclui a ID da conversa:

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

Em seguida, envie uma solicitação e especifique o parâmetro de conversa. (Para receber a resposta como eventos de streaming, definido "stream": true na solicitação.)

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?"
        }
      ]
    }
  ]
}

O agente retorna a resposta e salva os itens de conversa no armazenamento para recuperação posterior:

{
  "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  
}

A resposta inclui identificadores de conversa e mensagem, conteúdo e estatísticas de uso.

Para recuperar os itens de conversa, envie esta solicitação:

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

Isso retorna uma resposta JSON que contém mensagens de entrada e saída:

{
  "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
}

Expondo vários agentes

Você pode expor vários agentes simultaneamente usando ambos os protocolos:

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

Os agentes estarão disponíveis em:

  • Conclusões de chat: /math/v1/chat/completions e /science/v1/chat/completions
  • Respostas: /math/v1/responses e /science/v1/responses

Pontos de extremidade personalizados

Você pode personalizar os caminhos dos endpoints:

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

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

Conexão com endpoints compatíveis com OpenAI (Python)

O Python OpenAIChatClient e o OpenAIResponsesClient ambos suportam um parâmetro base_url, permitindo que você se conecte a qualquer endpoint compatível com OpenAI — incluindo agentes auto-hospedados, servidores locais de inferência (Ollama, LM Studio, vLLM) ou APIs compatíveis de terceiros com OpenAI.

pip install agent-framework --pre

Cliente de Conclusões de Chat

Use OpenAIChatClient para apontar para qualquer servidor compatível com base_url Conclusões de Chat:

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

Cliente de Respostas

Use OpenAIResponsesClient com base_url para pontos de extremidade que dão suporte à API de Respostas.

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

Servidores de OpenAI-Compatible comuns

A base_url abordagem funciona com qualquer servidor expondo o formato de Conclusões de Chat OpenAI:

Servidor URL base Anotações
Ollama http://localhost:11434/v1/ Inferência local, nenhuma chave de API necessária
LM Studio http://localhost:1234/v1/ Inferência local com GUI
vLLM http://localhost:8000/v1/ Serviço de alta taxa de transferência
Fundição de IA do Azure Seu endpoint de implantação Usa credenciais do Azure
Agentes do Framework de Hosted Agent Seu endpoint do agente Agentes do .NET expostos por meio de MapOpenAIChatCompletions

Observação

Você também pode definir a OPENAI_BASE_URL variável de ambiente em vez de passar base_url diretamente. O cliente o usará automaticamente.

Usando clientes do Azure OpenAI

As variantes do Azure OpenAI (AzureOpenAIChatClient, AzureOpenAIResponsesClient) conectam-se aos pontos de extremidade do Azure OpenAI usando credenciais do Azure — não é base_url necessário:

from agent_framework.azure import AzureOpenAIResponsesClient

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

Configurar com variáveis de ambiente:

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

Consulte Também

Próximas etapas

Purview

  • Last updated on