OpenAI

Microsoft Agent Framework поддерживает агенты OpenAI в C#, Python и Go. C# и Python поддерживают два типа клиентов OpenAI — Responses и Chat Completions, тогда как Go в настоящее время использует провайдер Chat Completions. Ответы — это рекомендуемый основной клиент, когда он доступен: он предназначен для более нового API ответов OpenAI и поддерживает полный набор размещенных средств (интерпретатор кода, поиск файлов, поиск в Интернете, размещенное MCP, создание образа). Используйте Chat Completion, если вам нужна широкая совместимость с моделями, поддержка Go или если вы хотите сохранить существующую интеграцию Chat Completions.

Тип клиента API Лучше всего для
Ответы (рекомендуется) API ответов Полнофункциональные агенты c размещенными инструментами (например, интерпретатор кода, поиск файлов, веб-поиск, размещенный MCP)
Завершение чата API завершения чата Простые агенты, широкая поддержка модели

Замечание

OpenAI объявила API Assistants устаревшим. Новый код должен использовать клиент Responses. Если вы переносите существующее приложение на основе помощников, ознакомьтесь с руководством по миграции Semantic Kernel.

Getting Started

Добавьте необходимые пакеты NuGet в проект.

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

Клиент для ответов

Клиент Responses является рекомендуемым основным клиентом и предоставляет самую богатую поддержку инструментов, включая интерпретатор кода, поиск файлов, поиск в Интернете и размещенный MCP.

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

Поддерживаемые средства: Функциональные средства, утверждение средств, интерпретатор кода, поиск файлов, поиск в Интернете, облачные средства MCP, локальные средства MCP.

Клиент завершения чата

Клиент завершения чата предоставляет простой способ создания агентов с помощью API завершения чата. Используйте это, если вам нужна широкая совместимость с моделями или у вас уже есть интеграция с 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."));

Поддерживаемые средства: Инструменты функций, веб-поиск, локальные инструменты MCP.

Клиент ассистентов

Замечание

API Помощников OpenAI не рекомендуется использовать OpenAI. В документации Agent Framework больше не описывается клиент Assistants — используйте приведённый выше клиент Responses в новом коде. Сведения о переносе существующего приложения см. в руководстве по миграции Semantic Kernel.

Использование агента

Оба типа клиентов формируют стандартный AIAgent, который поддерживает одни и те же операции агента (потоковая передача, треды, промежуточное ПО).

Дополнительные сведения см. в руководствах по началу работы.

Tools

Клиенты OpenAI .NET предоставляют различные области инструментов в зависимости от целевого API. Та же таблица применяется к соответствующим клиентам Azure OpenAI на странице поставщика Azure OpenAI.

инструмент Ответы Завершение чата
Средства функций ✅ ✅
Утверждение инструмента ✅ ✅
Интерпретатор кода ✅ ❌
Поиск файлов ✅ ❌
Поиск в Интернете ✅ ✅
Размещенные средства MCP ✅ ❌
Локальные средства MCP ✅ ✅

Замечание

Утверждение инструмента предоставляется клиентом чата, вызывающим функцию платформы, поэтому он работает с любым вызовом функции-инструмента независимо от базового API.

Замечание

Компания OpenAI объявила API OpenAI Assistants устаревшим, и для Python больше не поставляется клиент/провайдер совместимости с Assistants. Используйте OpenAIChatClient для Responses или OpenAIChatCompletionClient для Chat Completions. Если вы переходите с предыдущей версии Agent Framework Python, см. руководство по значительным изменениям в Python. Если выполняется миграция с Semantic Kernel, ознакомьтесь с руководством по миграции Semantic Kernel.

Tip

В Python Azure OpenAI теперь использует те же agent_framework.openai клиенты, что и здесь. Передайте явные входные данные маршрутизации Azure, такие как credential или azure_endpoint когда требуется маршрутизация Azure, а затем задайте api_version для поверхности API Azure, которую вы хотите использовать. Если OPENAI_API_KEY настроено, универсальные клиенты остаются в OpenAI, даже если AZURE_OPENAI_* переменные также присутствуют. Если у вас уже есть полный .../openai/v1 URL-адрес, используйте base_url вместо azure_endpoint. Сведения о конечных точках проекта Microsoft Foundry и службе агента Foundry см. на странице поставщика Microsoft Foundry. Сведения о локальных средах выполнения см. в разделе Foundry Local.

Installation

pip install agent-framework-openai

agent-framework-openai — это необязательный пакет поставщика Python для прямого использования OpenAI и Azure OpenAI.

Configuration

Клиенты чата Python OpenAI используют следующие шаблоны переменных среды:

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

Общие функции

Эти типы клиентов поддерживают следующие стандартные функции агента:

Инструменты функций

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)

Беседы с несколькими поворотами

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"

Стриминг

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

Быстрое кэширование

В моделях, поддерживающих явные точки останова кэша запросов, OpenAIChatClient можно использовать prompt_cache_keyprompt_cache_optionsи Content.additional_properties["prompt_cache_breakpoint"] управлять повторно используемым префиксом. Плата за запись кэша может взиматься отдельно в поддерживаемых моделях.

Использование кэша OpenAI нормализуется в response.usage_details:

  • cache_creation_input_token_count — входные маркеры, записанные в управляемый поставщиком кэш.
  • cache_read_input_token_count — входные маркеры, обслуживаемые из кэша.

Если включена функция OpenTelemetry, эти значения сопоставляются с gen_ai.usage.cache_creation.input_tokens и 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.")

Использование агента

Все типы клиентов создают стандарт Agent , поддерживающий одни и те же операции.

Дополнительные сведения см. в руководствах по началу работы.

Tools

Клиенты OpenAI Python предоставляют различные области инструментов в зависимости от базового API. OpenAIChatClient (Ответы) предоставляет размещённые фабрики инструментов через client.get_*_tool(...) — get_code_interpreter_tool, get_file_search_tool, get_web_search_tool, get_image_generation_tool, get_shell_tool и get_mcp_tool. OpenAIChatCompletionClient предоставляет только get_web_search_tool. Оба варианта работают с инструментами функций и локальными серверами MCP.

Та же матрица действует, если эти клиенты настроены на Azure OpenAI — см. Azure OpenAI.

инструмент OpenAIChatClient (Ответы) OpenAIChatCompletionClient (Завершение чата)
Средства функций ✅ ✅
Утверждение инструмента ✅ ✅
Интерпретатор кода ✅ ❌
Поиск файлов ✅ ❌
Поиск в Интернете ✅ ✅
Генерация изображений ✅ (get_image_generation_tool) ❌
Размещаемая оболочка ✅ (get_shell_tool) ❌
Размещенные средства MCP ✅ ❌
Локальные средства MCP ✅ ✅

Замечание

Утверждение инструмента обрабатывается клиентом чата, вызывающим функцию платформы, поэтому он работает с любым вызовом функции-инструмента независимо от базового API.

Завершение чата OpenAI

Пакет openaiprovider создает агенты с помощью API завершения чата OpenAI.

Installation

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

Direct OpenAI

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

Используйте тот же openaiprovider пакет с учетными данными 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{
        },
    },
)

Предупреждение

azidentity.NewDefaultAzureCredential удобно для разработки, но требует тщательного рассмотрения в рабочей среде. В рабочей среде рекомендуется использовать определенные учетные данные, например azidentity.NewManagedIdentityCredential, чтобы избежать проблем с задержкой, непреднамеренного проверки учетных данных и потенциальных рисков безопасности от резервных механизмов.

Настраиваемые параметры

Передайте параметры, специфичные для провайдера, с помощью openaiprovider.ChatCompletionNewParams:

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

Поддерживаемые средства: Инструменты функций, веб-поиск, локальные инструменты MCP.

Tip

Полные примеры см. в примере поставщика OpenAI и Azure примере OpenAI.

Дальнейшие действия

Microsoft Foundry

  • Last updated on