Agentes OpenAI

O Microsoft Agent Framework suporta agentes OpenAI em C#, Python e Go. C# e Python suportam dois tipos de clientes OpenAI — Respostas e Chat Completion — enquanto o Go utiliza atualmente o fornecedor Chat Completions. O Answers é o cliente principal recomendado quando disponível: direciona-se para a mais recente API OpenAI Responses e suporta todo o conjunto de ferramentas alojadas (interpretador de código, pesquisa de ficheiros, pesquisa web, MCP alojado, geração de imagens). Use Chat Completion quando precisar de ampla compatibilidade com modelos, suporte para Go ou tiver uma integração existente com Chat Completions que pretenda manter.

Tipo de Cliente	API	Melhor Para
Respostas (recomendado)	API de respostas	Agentes completos com ferramentas alojadas (interpretador de código, pesquisa de ficheiros, pesquisa web, MCP alojado)
Conclusão do Chat	API de Completação de Chat	Agentes simples, amplo suporte de modelos

Observação

A API dos Assistentes OpenAI está obsoleta pela OpenAI. O novo código deve usar o cliente Responses. Se estiver a migrar de uma aplicação já existente baseada em Assistentes, 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 Respostas é o cliente principal recomendado e oferece o suporte de ferramentas mais rico, incluindo interpretador de código, pesquisa de ficheiros, pesquisa web e MCP alojado.

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 suportadas: Ferramentas funcionais, aprovação de ferramentas, interpretador de código, pesquisa de ficheiros, pesquisa web, MCP alojado, ferramentas locais de MCP.

Cliente de Conclusão de Chat

O cliente Chat Completion oferece uma forma direta de criar agentes usando a API Chat Completions. Use-o quando precisar de uma ampla compatibilidade de modelos ou quando tiver uma integração já 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 suportadas: Ferramentas funcionais, pesquisa na web, ferramentas MCP locais.

Assistentes de Cliente

Observação

A API dos Assistentes OpenAI está obsoleta pela OpenAI. O Agent Framework já não documenta um cliente Assistants — use o cliente Responses acima para novo código. Para migrar uma aplicação existente, consulte o guia de migração Kernel Semântico.

Usando o agente

Ambos os tipos de cliente produzem um AIAgent padrão que suporta as mesmas operações do agente (streaming, threads, middleware).

Para mais informações, consulte os tutoriais para começar.

Tools

Os clientes OpenAI .NET expõem diferentes superfícies de ferramentas dependendo da API que pretendem. A mesma matriz aplica-se aos clientes Azure OpenAI correspondentes na página do fornecedor Azure OpenAI.

Tool	Respostas	Conclusão do bate-papo
Ferramentas Funcionais	✅	✅
Aprovação de Ferramentas	✅	✅
Intérprete de código	✅	❌
Pesquisa de ficheiros	✅	❌
Pesquisa na Web	✅	✅
Ferramentas MCP Hospedadas	✅	❌
Ferramentas MCP Locais	✅	✅

Observação

A Aprovação de Ferramentas é fornecida pelo cliente de chat invocador de funções do framework, pelo que funciona com qualquer chamada de função e ferramenta, independentemente da API subjacente.

Observação

A API dos Assistentes OpenAI está obsoleta pela OpenAI, e o Python já não fornece um cliente/fornecedor de compatibilidade com os Assistentes. Use OpenAIChatClient para respostas ou OpenAIChatCompletionClient para completar chats. Se estiver a migrar de uma versão anterior do Agent Framework Python, consulte o guia Python alterações significativas. Se estiver a migrar de Kernel Semântico, consulte o guia de migração Kernel Semântico.

Sugestão

Em Python, o Azure OpenAI utiliza agora os mesmos agent_framework.openai clientes mostrados aqui. Passe entradas explícitas de roteamento do Azure, como credential ou azure_endpoint, quando quiser o roteamento do Azure, depois defina api_version para a superfície da API do Azure que deseja usar. Se OPENAI_API_KEY estiver configurado, os clientes genéricos permanecem no OpenAI, mesmo quando também existem variáveis AZURE_OPENAI_* presentes. Se já tiver um URL completo .../openai/v1 , use base_url em vez de azure_endpoint. Para os endpoints do projeto Microsoft Foundry e o Serviço de Agentes Foundry, consulte a página do fornecedor Microsoft Foundry. Para horários locais, veja Foundry Local.

Installation

pip install agent-framework-openai

agent-framework-openai é o pacote opcional do fornecedor Python tanto para o uso direto do OpenAI como do Azure OpenAI.

Configuração

Os clientes de chat OpenAI em Python utilizam estes padrões de variáveis de ambiente:

Respostas

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

Conclusão do Chat

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

Azure OpenAI com os mesmos clientes

O Azure OpenAI usa agora os mesmos clientes Python OpenAI que o OpenAI direto. O padrão Azure preferido e mais claro é passar entradas explícitas de encaminhamento Azure, como credential ou azure_endpoint, e depois configurar api_version para o Azure assim que a seleção de encaminhamento estiver concluída. Caso OPENAI_API_KEY seja definido, os clientes genéricos permanecem no OpenAI, a menos que forneças esses dados de encaminhamento do Azure. Se só tiver AZURE_OPENAI_* definições, o mecanismo de substituição do ambiente Azure continua a funcionar. OpenAIChatClient prefere AZURE_OPENAI_CHAT_MODEL, OpenAIChatCompletionClient prefere AZURE_OPENAI_CHAT_COMPLETION_MODEL, e ambos voltam a AZURE_OPENAI_MODEL.

AZURE_OPENAI_ENDPOINT="https://<resource>.openai.azure.com"
AZURE_OPENAI_CHAT_MODEL="gpt-4o-mini"
# Optional shared fallback:
# AZURE_OPENAI_MODEL="gpt-4o-mini"
AZURE_OPENAI_API_VERSION="your-api-version"

import asyncio
import os
from agent_framework.openai import OpenAIChatClient
from azure.identity import AzureCliCredential

async def main():
    agent = OpenAIChatClient(
        model=os.environ["AZURE_OPENAI_CHAT_MODEL"],
        azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
        api_version=os.getenv("AZURE_OPENAI_API_VERSION"),
        credential=AzureCliCredential(),
    ).as_agent(
        name="AzureOpenAIResponsesAgent",
        instructions="You are a helpful assistant.",
    )

    result = await agent.run("Hello!")
    print(result)

asyncio.run(main())

Se já tens uma URL completa do Azure OpenAI que termina em /openai/v1, passa-a como base_url em vez de azure_endpoint. Mantenha-se api_version alinhado com a superfície da API Azure OpenAI que está a usar. Se OPENAI_API_KEY também estiver definido no teu ambiente, estas entradas explícitas do Azure mantêm o cliente no Azure.

Observação

Use OpenAIChatClient para a API de Respostas. Para autenticação de chave do Azure, ainda podes passar api_key, mas credential= agora é a superfície de autenticação preferida do Azure.

Azure embeddings com a mesma família de clientes

OpenAIEmbeddingClient Segue as mesmas regras de roteamento que os clientes de chat. Para as integrações do Azure, passe a implementação da integração como model e prefira utilizar entradas explícitas do Azure.

import os
from agent_framework.openai import OpenAIEmbeddingClient
from azure.identity import AzureCliCredential

client = OpenAIEmbeddingClient(
    model=os.environ["AZURE_OPENAI_EMBEDDING_MODEL"],
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version=os.getenv("AZURE_OPENAI_API_VERSION"),
    credential=AzureCliCredential(),
)

Criar Agentes OpenAI

Respostas

OpenAIChatClient utiliza a API Responses — o cliente primário recomendado com suporte a ferramentas alojadas.

import asyncio
from agent_framework.openai import OpenAIChatClient

async def main():
    agent = OpenAIChatClient().as_agent(
        name="FullFeaturedAgent",
        instructions="You are a helpful assistant with access to many tools.",
    )
    result = await agent.run("Write and run a Python script that calculates fibonacci numbers.")
    print(result)

asyncio.run(main())

Ferramentas suportadas: Ferramentas funcionais, aprovação de ferramentas, interpretador de código, pesquisa de ficheiros, pesquisa web, MCP alojado, ferramentas locais de MCP.

Ferramentas Alojadas com Cliente de Respostas

O cliente Respostas fornece get_*_tool() métodos para cada tipo de ferramenta alojada:

async def hosted_tools_example():
    client = OpenAIChatClient()

    # Each tool is created via a client method
    code_interpreter = client.get_code_interpreter_tool()
    web_search = client.get_web_search_tool()
    file_search = client.get_file_search_tool(vector_store_ids=["vs_abc123"])
    mcp_tool = client.get_mcp_tool(
        name="GitHub",
        url="https://api.githubcopilot.com/mcp/",
        approval_mode="never_require",
    )

    agent = client.as_agent(
        name="PowerAgent",
        instructions="You have access to code execution, web search, files, and GitHub.",
        tools=[code_interpreter, web_search, file_search, mcp_tool],
    )
    result = await agent.run("Search the web for Python best practices, then write a summary.")
    print(result)

Conclusão do Chat

OpenAIChatCompletionClient utiliza a API Chat Completions — use-a quando precisar de ampla compatibilidade de modelos ou quando tiver uma integração Chat Completions existente.

import asyncio
from agent_framework.openai import OpenAIChatCompletionClient

async def main():
    agent = OpenAIChatCompletionClient().as_agent(
        name="HelpfulAssistant",
        instructions="You are a helpful assistant.",
    )
    result = await agent.run("Hello, how can you help me?")
    print(result)

asyncio.run(main())

Ferramentas suportadas: Ferramentas funcionais, pesquisa na web, ferramentas MCP locais.

Pesquisa na Web com Conclusão de Chat

async def web_search_example():
    client = OpenAIChatCompletionClient()
    web_search = client.get_web_search_tool()

    agent = client.as_agent(
        name="SearchBot",
        instructions="You can search the web for current information.",
        tools=web_search,
    )
    result = await agent.run("What are the latest developments in AI?")
    print(result)

Importante

O Python já não fornece um cliente/provedor de compatibilidade para Assistentes. Para código Python atual, use OpenAIChatClient para cenários da API de Respostas ou OpenAIChatCompletionClient para Completões de Chat. Se precisar de um agente de gestão de serviços no Microsoft Foundry, consulte a página do fornecedor Microsoft Foundry.

Características Comuns

Estes tipos de clientes suportam estas funcionalidades padrão de agente:

Ferramentas de Função

from agent_framework import 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 = OpenAIChatClient().as_agent(
        instructions="You are a weather assistant.",
        tools=get_weather,
    )
    result = await agent.run("What's the weather in Tokyo?")
    print(result)

Conversas com Múltiplos Turnos

async def thread_example():
    agent = OpenAIChatClient().as_agent(
        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"

Serviço de streaming

async def streaming_example():
    agent = OpenAIChatClient().as_agent(
        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()

Usando o agente

Todos os tipos de cliente produzem um padrão Agent que suporta as mesmas operações.

Para mais informações, consulte os tutoriais para começar.

Tools

Os clientes OpenAI em Python expõem diferentes superfícies de ferramentas dependendo da API subjacente. OpenAIChatClient (Respostas) as naves alojavam fábricas de ferramentas via 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 apenas expõe get_web_search_tool. Ambos funcionam com ferramentas funcionais e servidores MCP locais.

A mesma matriz aplica-se quando aponta estes clientes para Azure OpenAI — veja Azure OpenAI.

Tool	OpenAIChatClient (Respostas)	OpenAIChatCompletionClient (Conversa Concluída)
Ferramentas Funcionais	✅	✅
Aprovação de Ferramentas	✅	✅
Intérprete de código	✅	❌
Pesquisa de ficheiros	✅	❌
Pesquisa na Web	✅	✅
Geração de Imagem	✅ (get_image_generation_tool)	❌
Shell Hospedado	✅ (get_shell_tool)	❌
Ferramentas MCP Hospedadas	✅	❌
Ferramentas MCP Locais	✅	✅

Observação

A Aprovação de Ferramentas é gerida pelo cliente de chat invocador de funções do framework, pelo que funciona com qualquer chamada de função e ferramenta, independentemente da API subjacente.

Conclusões do OpenAI Chat

O openaiprovider pacote cria agentes usando a API OpenAI Chat Completions.

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

Azure OpenAI

Use o mesmo openaiprovider pacote com credenciais 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, sondagens não intencionais de credenciais e potenciais riscos de segurança provenientes de mecanismos de recurso.

Opções personalizadas

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

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

Ferramentas suportadas: Ferramentas funcionais, pesquisa na web, ferramentas MCP locais.

Sugestão

Consulte o exemplo do fornecedor OpenAI e o exemplo do OpenAI do Azure para exemplos completos.

Próximos passos

Microsoft Foundry