Agenci OpenAI

platforma Microsoft Agent Framework obsługuje dwa typy klientów OpenAI — odpowiedzi i uzupełnianie czatu — zarówno w języku C#, jak i Python. Responses jest zalecanym głównym klientem: jest przeznaczony dla nowszego interfejsu OpenAI Responses API i obsługuje pełny zestaw hostowanych narzędzi (interpreter kodu, wyszukiwanie plików, wyszukiwanie w sieci, hostowany MCP, generowanie obrazów). Użyj Chat Completion, jeśli potrzebujesz szerokiej zgodności z modelami lub masz istniejącą integrację z Chat Completions, którą chcesz zachować.

Typ klienta	API	Najlepsze dla
Odpowiedzi (zalecane)	API odpowiedzi	Agenci o pełnej funkcjonalności z hostowanymi narzędziami (interpretor kodu, wyszukiwanie plików, wyszukiwanie w Internecie, hostowana aplikacja MCP)
Uzupełnianie czatu	API Uzupełnień Czatowych	Proste agenty, szerokie wsparcie dla modeli

Uwaga / Notatka

API asystentów OpenAI zostało wycofane przez OpenAI. Nowy kod powinien używać klienta Responses. Jeśli przeprowadzasz migrację z istniejącej aplikacji opartej na asystentach, zapoznaj się z przewodnikiem migracji Semantic Kernel.

Wprowadzenie

Dodaj wymagane pakiety NuGet do projektu.

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

Klient odpowiedzi

Klient odpowiedzi jest zalecanym klientem podstawowym i zapewnia najbogatszą obsługę narzędzi, w tym interpreter kodu, wyszukiwanie plików, wyszukiwanie w Internecie i hostowaną aplikację MCP.

using Microsoft.Agents.AI;
using OpenAI;

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

AIAgent agent = responsesClient.AsAIAgent(
    instructions: "You are a helpful coding assistant.",
    name: "CodeHelper");

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

Obsługiwane narzędzia: Narzędzia funkcji, zatwierdzanie narzędzi, interpreter kodu, wyszukiwanie plików, wyszukiwanie w Internecie, hostowane MCP, lokalne narzędzia MCP.

Klient uzupełniania rozmów czatowych

Klient Chat Completions zapewnia prosty sposób tworzenia agentów przy użyciu interfejsu Chat Completions API. Użyj tego, gdy potrzebujesz zgodności z wieloma modelami lub masz istniejącą integrację z 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."));

Obsługiwane narzędzia: Narzędzia funkcji, wyszukiwanie w Internecie, lokalne narzędzia MCP.

Klient asystentów

Uwaga / Notatka

API OpenAI Assistants zostało wycofane przez OpenAI. Framework Agent nie zawiera już dokumentacji klienta Assistants — do nowego kodu użyj powyższego klienta Responses. Aby przeprowadzić migrację istniejącej aplikacji, zobacz przewodnik migracji Semantic Kernel.

Korzystanie z agenta

Oba typy klientów generują standard AIAgent, który obsługuje te same operacje agenta (przesyłanie strumieniowe, wątki, oprogramowanie pośredniczące).

Aby uzyskać więcej informacji, zobacz samouczki 'Pierwsze kroki'.

Tools

Klienci .NET OpenAI uwidaczniają różne powierzchnie narzędzi w zależności od docelowego interfejsu API. Ta sama macierz ma zastosowanie do odpowiadających klientów Azure OpenAI na stronie dostawcy Azure OpenAI.

Tool	Responses	Zakończenie czatu
Narzędzia funkcji	✅	✅
Zatwierdzanie narzędzi	✅	✅
Interpreter kodów	✅	❌
Wyszukiwanie plików	✅	❌
Wyszukiwanie w Sieci Web	✅	✅
Hostowane narzędzia MCP	✅	❌
Lokalne narzędzia MCP	✅	✅

Uwaga / Notatka

Akceptacja narzędzia jest zapewniana przez klienta czatu platformy wywołującego funkcje, dzięki czemu działa z dowolnym wywołaniem narzędzia-funkcji niezależnie od bazowego API.

Uwaga / Notatka

Interfejs API Asystentów OpenAI został wycofany przez OpenAI, a Python nie udostępnia już klienta/dostawcy zgodności dla Asystentów. Użyj OpenAIChatClient dla Odpowiedzi lub OpenAIChatCompletionClient dla Uzupełnień czatu. Jeśli przeprowadzasz migrację z poprzedniego wydania platformy Agent Framework dla języka Python, zapoznaj się z przewodnikiem po istotnych zmianach w języku Python. Jeśli przeprowadzasz migrację z Semantic Kernel, zobacz przewodnik migracji Semantic Kernel.

Tip

W języku Python usługa Azure OpenAI korzysta teraz z tych samych agent_framework.openai klientów przedstawionych tutaj. Przekaż jawne dane wejściowe routingu platformy Azure, takie jak credential lub azure_endpoint gdy chcesz użyć routingu platformy Azure, a następnie ustaw api_version dla powierzchni interfejsu API platformy Azure, której chcesz użyć. Jeśli OPENAI_API_KEY jest skonfigurowany, klienci ogólni pozostają na platformie OpenAI nawet wtedy, gdy zmienne AZURE_OPENAI_* również są obecne. Jeśli masz już pełny .../openai/v1 adres URL, użyj polecenia base_url zamiast azure_endpoint. W przypadku punktów końcowych projektu Microsoft Foundry i usługi agenta foundry zobacz stronę dostawcy rozwiązania Microsoft Foundry. Aby uzyskać informacje o lokalnych środowiskach uruchomieniowych, zobacz Foundry Local (Lokalne środowisko uruchomieniowe usługi Foundry).

Instalacja

pip install agent-framework-openai

agent-framework-openai jest opcjonalnym pakietem dostawcy języka Python dla użycia bezpośredniego interfejsu OpenAI i usługi Azure OpenAI.

Konfiguracja

Klienci czatu OpenAI języka Python używają tych wzorców zmiennych środowiskowych:

Odpowiedzi

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

Uzupełnianie czatu

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

Usługa Azure OpenAI z tymi samymi klientami

Usługa Azure OpenAI używa teraz tych samych klientów OpenAI w języku Python co bezpośrednia usługa OpenAI. Preferowanym i najczystszym wzorcem platformy Azure jest przekazywanie jawnych danych wejściowych routingu platformy Azure, takich jak credential lub azure_endpoint, a następnie ustawiania api_version dla platformy Azure po wybraniu routingu. Jeśli OPENAI_API_KEY jest ustawiona, klienci ogólni pozostają na OpenAI, chyba że przekażesz te dane routingu Azure. Jeśli masz tylko AZURE_OPENAI_* ustawienia, środowisko zapasowe platformy Azure nadal działa. OpenAIChatClient preferuje AZURE_OPENAI_CHAT_MODEL, OpenAIChatCompletionClient preferuje AZURE_OPENAI_CHAT_COMPLETION_MODEL, a oba wracają do 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())

Jeśli masz już pełny adres URL usługi Azure OpenAI kończący się ciągiem /openai/v1, przekaż go jako base_url zamiast azure_endpoint. Zachowaj api_version dopasowanie do interfejsu API usługi Azure OpenAI, z którego korzystasz. Jeśli OPENAI_API_KEY jest również skonfigurowane w twoim środowisku, te jawnie skonfigurowane dane wejściowe Azure utrzymują klienta na platformie Azure.

Uwaga / Notatka

Użyj OpenAIChatClient dla interfejsu API odpowiedzi. W przypadku uwierzytelniania klucza platformy Azure nadal można przekazać api_key, ale credential= jest teraz preferowanym interfejsem uwierzytelniania.

Osadzanie platformy Azure z tą samą rodziną klientów

OpenAIEmbeddingClient jest zgodny z tymi samymi regułami routingu co klienci rozmów. W przypadku osadzania w Azure przekaż wdrożenie osadzania jako model i preferuj jawne dane wejściowe dla platformy 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(),
)

Tworzenie agentów OpenAI

Odpowiedzi

OpenAIChatClient korzysta z Responses API — zalecanego podstawowego klienta z obsługą hostowanych narzędzi.

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

Obsługiwane narzędzia: Narzędzia funkcji, zatwierdzanie narzędzi, interpreter kodu, wyszukiwanie plików, wyszukiwanie w Internecie, hostowane MCP, lokalne narzędzia MCP.

Hostowane narzędzia z klientem odpowiedzi

Klient Odpowiedzi udostępnia get_*_tool() metody dla każdego typu hostowanego narzędzia:

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)

Uzupełnianie czatu

OpenAIChatCompletionClient używa interfejsu Chat Completions API — użyj go, gdy potrzebujesz szerokiej zgodności z modelami lub masz istniejącą integrację z Chat Completions.

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

Obsługiwane narzędzia: Narzędzia funkcji, wyszukiwanie w Internecie, lokalne narzędzia MCP.

Wyszukiwanie w Internecie z uzupełnianiem czatu

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)

Ważna

Python nie dostarcza już klienta lub dostawcy do współpracy z asystentami. W przypadku bieżącego kodu w języku Python użyj OpenAIChatClient w scenariuszach API odpowiedzi lub OpenAIChatCompletionClient dla uzupełniania czatu. Jeśli potrzebujesz agenta zarządzanego przez usługę w rozwiązaniu Microsoft Foundry, zobacz stronę dostawcy rozwiązania Microsoft Foundry.

Typowe funkcje

Te typy klientów obsługują następujące standardowe funkcje agenta:

Narzędzia funkcji

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)

Konwersacje wieloetapowe

async def thread_example():
    agent = OpenAIChatClient().as_agent(
        instructions="You are a helpful assistant.",
    )
    session = await 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

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

Korzystanie z agenta

Wszystkie typy klientów tworzą standard Agent , który obsługuje te same operacje.

Aby uzyskać więcej informacji, zobacz samouczki 'Pierwsze kroki'.

Tools

Klienci Python OpenAI uwidaczniają różne powierzchnie narzędzi w zależności od bazowego interfejsu API. OpenAIChatClient (Odpowiedzi) udostępnia hostowane fabryki narzędzi za pośrednictwem client.get_*_tool(...) — get_code_interpreter_tool, get_file_search_tool, get_web_search_tool, get_image_generation_tool, get_shell_tool i get_mcp_tool. OpenAIChatCompletionClient uwidacznia get_web_search_tooltylko . Obie współpracują z narzędziami funkcyjnymi i lokalnymi serwerami MCP.

Ta sama macierz obowiązuje, gdy kierujesz tych klientów do usługi Azure OpenAI — zobacz Azure OpenAI.

Tool	OpenAIChatClient (Odpowiedzi)	OpenAIChatCompletionClient (Ukończenie czatu)
Narzędzia funkcji	✅	✅
Zatwierdzanie narzędzi	✅	✅
Interpreter kodów	✅	❌
Wyszukiwanie plików	✅	❌
Wyszukiwanie w Sieci Web	✅	✅
Generowanie obrazu	✅ (get_image_generation_tool)	❌
Powłoka hostowana	✅ (get_shell_tool)	❌
Hostowane narzędzia MCP	✅	❌
Lokalne narzędzia MCP	✅	✅

Uwaga / Notatka

Zatwierdzanie narzędzi jest obsługiwane przez klienta czatu platformy obsługującego wywoływanie funkcji, dzięki czemu działa z dowolnym wywołaniem funkcji-narzędzia, niezależnie od używanego interfejsu API.

Dalsze kroki

Microsoft Foundry