OpenAI

Microsoft Agent Framework dá suporte a agentes OpenAI em C#, Python e Go. C# e Python dão suporte a dois tipos de cliente OpenAI — Respostas e Preenchimento de Chat — enquanto o Go atualmente usa o provedor de Conclusões de Chat. As respostas são o cliente primário recomendado quando disponível: ele tem como destino a API de Respostas OpenAI mais recente e dá suporte ao conjunto completo de ferramentas hospedadas (interpretador de código, pesquisa de arquivos, pesquisa na Web, MCP hospedado, geração de imagem). Use Chat Completion quando precisar de ampla compatibilidade com modelos, suporte a Go ou já tiver uma integração existente com Chat Completions que deseja manter.

Tipo de cliente API Mais adequado para
Respostas (recomendado) API de respostas Agentes completos com ferramentas hospedadas (interpretador de código, pesquisa de arquivo, pesquisa na Web, MCP hospedado)
Conclusão do chat API de Conclusões de Chat Agentes simples, amplo suporte a modelos

Note

A API de Assistentes do OpenAI é preterida pelo OpenAI. O novo código deve usar o cliente Responses. Se você estiver migrando de um aplicativo baseado em Assistentes existente, consulte o guia de migração Kernel semântico.

Introdução

Adicione os pacotes NuGet necessários ao seu projeto.

dotnet add package Microsoft.Agents.AI.OpenAI --prerelease

Cliente de Respostas

O cliente de Respostas é o cliente primário recomendado e fornece o suporte de ferramenta mais avançado, incluindo interpretador de código, pesquisa de arquivo, pesquisa na Web e MCP hospedado.

using Microsoft.Agents.AI;
using OpenAI;

OpenAIClient client = new OpenAIClient("<your_api_key>");
var responsesClient = client.GetResponsesClient();

AIAgent agent = responsesClient.AsAIAgent(
    model: "gpt-4o-mini",
    instructions: "You are a helpful coding assistant.",
    name: "CodeHelper");

Console.WriteLine(await agent.RunAsync("Write a Python function to sort a list."));

Ferramentas com suporte: Ferramentas de funções, aprovação da ferramenta, interpretador de código, pesquisa de arquivo, pesquisa na Web, MCP hospedado, ferramentas MCP locais.

Cliente de conclusão de chat

O cliente de Conclusão de Chat fornece uma maneira simples de criar agentes usando a API de Conclusões de Chat. Use-o quando precisar de ampla compatibilidade com modelos ou já tiver uma integração existente com o Chat Completions.

using Microsoft.Agents.AI;
using OpenAI;

OpenAIClient client = new OpenAIClient("<your_api_key>");
var chatClient = client.GetChatClient("gpt-4o-mini");

AIAgent agent = chatClient.AsAIAgent(
    instructions: "You are good at telling jokes.",
    name: "Joker");

Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));

Ferramentas com suporte: Ferramentas de funções, pesquisa na Web, ferramentas MCP locais.

Cliente de Assistentes

Note

A API de Assistentes do OpenAI é preterida pelo OpenAI. O framework de agentes não documenta mais um cliente Assistants — use o cliente Responses acima para novos códigos. Para migrar um aplicativo existente, consulte o guia de migração Kernel semântico.

Usando o agente

Ambos os tipos de cliente produzem um padrão AIAgent que dá suporte às mesmas operações de agente (streaming, threads, middleware).

Para obter mais informações, consulte os tutoriais de Introdução.

Tools

Os clientes .NET OpenAI expõem diferentes superfícies de ferramenta, dependendo de qual API eles visam. A mesma matriz se aplica aos clientes OpenAI Azure correspondentes na página do provedor Azure OpenAI.

Tool Responses Conclusão do chat
Ferramentas de Funções ✅ ✅
Aprovação da ferramenta ✅ ✅
Interpretador de Código ✅ ❌
Pesquisa de Arquivo ✅ ❌
Pesquisa na Web ✅ ✅
Ferramentas MCP hospedadas ✅ ❌
Ferramentas MCP locais ✅ ✅

Note

Aprovação de Ferramenta é fornecida pelo cliente de chat do framework com invocação de funções, portanto funciona com qualquer chamada de ferramenta baseada em função, independentemente da API subjacente.

Note

A API Assistants da OpenAI foi descontinuada pela OpenAI, e o Python não inclui mais um cliente/provedor de compatibilidade para Assistants. Use OpenAIChatClient para respostas ou OpenAIChatCompletionClient para conclusões de chat. Se você estiver migrando de uma versão anterior do Agent Framework Python, consulte o guia Python alterações significativas. Se você estiver migrando de Kernel semântico, consulte o guia de migração Kernel semântico.

Dica

No Python, o Azure OpenAI agora usa os mesmos agent_framework.openai clientes mostrados aqui. Passe entradas explícitas de roteamento do Azure, como credential ou azure_endpoint quando desejar roteamento do Azure, e defina api_version para a superfície da API do Azure que você deseja usar. Se OPENAI_API_KEY estiver configurado, os clientes genéricos permanecerão no OpenAI mesmo quando AZURE_OPENAI_* variáveis também estiverem presentes. Se você já tiver uma URL completa .../openai/v1 , use base_url em vez de azure_endpoint. Para os pontos de extremidade de projeto do Microsoft Foundry e o Serviço do Agente Foundry, consulte a página do provedor do Microsoft Foundry. Para runtimes locais, consulte Foundry Local.

Installation

pip install agent-framework-openai

agent-framework-openai é o pacote de provedor python opcional para uso direto do OpenAI e do Azure OpenAI.

Configuration

Os clientes de chat do Python OpenAI usam esses padrões de variável de ambiente:

OPENAI_API_KEY="your-openai-api-key"
OPENAI_CHAT_MODEL="gpt-4o-mini"
# Optional shared fallback:
# OPENAI_MODEL="gpt-4o-mini"

Recursos comuns

Esses tipos de cliente dão suporte a esses recursos de agente padrão:

Ferramentas de Funções

from agent_framework import Agent, tool

@tool
def get_weather(location: str) -> str:
    """Get the weather for a given location."""
    return f"The weather in {location} is sunny, 25°C."

async def example():
    agent = Agent(
        client=OpenAIChatClient(),
        instructions="You are a weather assistant.",
        tools=get_weather,
    )
    result = await agent.run("What's the weather in Tokyo?")
    print(result)

Conversas de várias voltas

from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient

async def thread_example():
    agent = Agent(
        client=OpenAIChatClient(),
        instructions="You are a helpful assistant.",
    )
    session = agent.create_session()

    result1 = await agent.run("My name is Alice", session=session)
    print(result1)
    result2 = await agent.run("What's my name?", session=session)
    print(result2)  # Remembers "Alice"

Streaming

from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient

async def streaming_example():
    agent = Agent(
        client=OpenAIChatClient(),
        instructions="You are a creative storyteller.",
    )
    print("Agent: ", end="", flush=True)
    async for chunk in agent.run("Tell me a short story about AI.", stream=True):
        if chunk.text:
            print(chunk.text, end="", flush=True)
    print()

Armazenamento de prompts em cache

Em modelos que dão suporte a pontos de interrupção explícitos de cache de prompt, OpenAIChatClient podem usar prompt_cache_keyprompt_cache_optionse Content.additional_properties["prompt_cache_breakpoint"] controlar o prefixo reutilizável. As gravações de cache podem ser cobradas separadamente em modelos com suporte.

O uso do cache OpenAI é normalizado em response.usage_details:

  • cache_creation_input_token_count - Tokens de entrada gravados no cache gerenciado pelo provedor.
  • cache_read_input_token_count - Tokens de entrada servidos do cache.

Quando OpenTelemetry está habilitado, esses valores são mapeados para gen_ai.usage.cache_creation.input_tokens e gen_ai.usage.cache_read.input_tokens.

import asyncio
import time

from agent_framework import Content, Message
from agent_framework.openai import OpenAIChatClient, OpenAIChatOptions
from dotenv import load_dotenv

load_dotenv()
# A stable block of context that is reused across requests, for example a product
# catalog, a policy document, or long system guidance. Repeated here to clear the
# 1024-token minimum a cache breakpoint requires.
STABLE_CONTEXT = (
    "You are a support assistant for the Contoso appliance store. "
    "Always answer briefly, quote the relevant catalog section, and never invent "
    "model numbers. If a question is out of scope, say so and point the customer "
    "to support@contoso.example. "
) * 40


def build_messages(question: str) -> list[Message]:
    """Build a request with a cache breakpoint at the end of the stable prefix."""
    return [
        Message(
            role="user",
            contents=[
                Content.from_text(
                    STABLE_CONTEXT,
                    additional_properties={"prompt_cache_breakpoint": {"mode": "explicit"}},
                )
            ],
        ),
        Message(role="user", contents=[Content.from_text(question)]),
    ]


async def main() -> None:
    print("\033[92m=== OpenAI Chat Client Prompt Caching Example ===\033[0m\n")

    client = OpenAIChatClient[OpenAIChatOptions](model="gpt-5.6-luna")
    options: OpenAIChatOptions = {
        "prompt_cache_options": {"mode": "explicit"},
        "prompt_cache_key": f"contoso_appliance_store-{time.time()}",
    }

    questions = ["Do you sell refrigerators?", "What is the return policy contact?"]
    for turn, question in enumerate(questions, start=1):
        response = await client.get_response(build_messages(question), options=options)
        usage = response.usage_details or {}
        cached = usage.get("cache_read_input_token_count", 0)
        cached_write = usage.get("cache_creation_input_token_count", 0)
        print(f"Turn {turn}: {question}")
        print(f"  Answer: {response.text}")
        print(f"  Cached input tokens (read): {cached}\n")
        print(f"  Cached input tokens (created): {cached_write}\n")
        if turn < len(questions):
            # A freshly written cache entry becomes readable shortly after the request
            # completes; the brief pause keeps the next turn from racing this one.
            await asyncio.sleep(2)

    print("The first turn writes the prefix to the cache; later turns read it back.")

Usando o agente

Todos os tipos de cliente produzem um padrão Agent que dá suporte às mesmas operações.

Para obter mais informações, consulte os tutoriais de Introdução.

Tools

Os clientes Python OpenAI expõem diferentes superfícies de ferramenta, dependendo da API subjacente. OpenAIChatClient (Respostas) fornece fábricas de ferramentas hospedadas por meio de client.get_*_tool(...) — get_code_interpreter_tool, get_file_search_tool, get_web_search_tool, get_image_generation_tool, get_shell_tool e get_mcp_tool. OpenAIChatCompletionClient só expõe get_web_search_tool. Ambos funcionam com ferramentas de função e servidores MCP locais.

A mesma matriz se aplica quando você aponta esses clientes para Azure OpenAI — consulte Azure OpenAI.

Tool OpenAIChatClient (Respostas) OpenAIChatCompletionClient (Conclusão do chat)
Ferramentas de Funções ✅ ✅
Aprovação da ferramenta ✅ ✅
Interpretador de Código ✅ ❌
Pesquisa de Arquivo ✅ ❌
Pesquisa na Web ✅ ✅
Geração de imagem ✅ (get_image_generation_tool) ❌
Shell hospedado ✅ (get_shell_tool) ❌
Ferramentas MCP hospedadas ✅ ❌
Ferramentas MCP locais ✅ ✅

Note

Aprovação de Ferramenta é tratada pelo cliente de chat com chamada de função do framework, portanto funciona com qualquer chamada de ferramenta baseada em função, independentemente da API subjacente.

Conclusões de chat do OpenAI

O openaiprovider pacote cria agentes usando a API de Conclusões de Chat do OpenAI.

Installation

go get github.com/microsoft/agent-framework-go

OpenAI Direct

import (
    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/provider/openaiprovider"

    "github.com/openai/openai-go/v3"
)

a := openaiprovider.NewChatCompletionsAgent(
    openai.NewClient(), // uses OPENAI_API_KEY env var
    openaiprovider.AgentConfig{
        Model: "gpt-4o-mini",
        Instructions: "You are a helpful assistant.",
        Config: agent.Config{
            Name:         "MyAgent",
        },
    },
)

resp, err := a.RunText(ctx, "Tell me a joke.").Collect()

OpenAI do Azure

Use o mesmo openaiprovider pacote com credenciais de Azure:

import (
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    openai "github.com/openai/openai-go/v3"
    "github.com/openai/openai-go/v3/azure"
)

token, _ := azidentity.NewDefaultAzureCredential(nil)

a := openaiprovider.NewChatCompletionsAgent(
    openai.NewClient(
        azure.WithEndpoint(endpoint, apiVersion),
        azure.WithTokenCredential(token),
    ),
    openaiprovider.AgentConfig{
        Model: deployment,
        Instructions: "You are a helpful assistant.",
        Config: agent.Config{
        },
    },
)

Warning

azidentity.NewDefaultAzureCredential é conveniente para o desenvolvimento, mas requer uma consideração cuidadosa na produção. Em produção, considere usar uma credencial específica, como azidentity.NewManagedIdentityCredential, para evitar problemas de latência, tentativas não intencionais de credenciais e possíveis riscos de segurança decorrentes de mecanismos de fallback.

Opções personalizadas

Passe opções específicas do provedor usando openaiprovider.ChatCompletionNewParams:

resp, err := a.RunText(ctx, "Hello!",
    openaiprovider.ChatCompletionNewParams(openai.ChatCompletionNewParams{
        Temperature: openai.Float(0.7),
    }),
).Collect()

Ferramentas com suporte: Ferramentas de funções, pesquisa na Web, ferramentas MCP locais.

Dica

Consulte o exemplo do provedor OpenAI e o exemplo do Azure OpenAI para ver exemplos completos.

Próximas Etapas 

Microsoft Foundry

  • Last updated on