Agenti OpenAI

Microsoft Agent Framework supporta due tipi di client OpenAI, ovvero risposte e completamento della chat, sia in C# che in Python. Le risposte sono il client primario consigliato: è destinato all'API Risposte OpenAI più recente e supporta il set completo di strumenti ospitati (interprete del codice, ricerca di file, ricerca Web, MCP ospitato, generazione di immagini). Usa Chat Completion quando ti serve un'ampia compatibilità con i modelli o se hai un'integrazione esistente con Chat Completions da mantenere.

Tipo di client	API	Ideale per
Risposte (scelta consigliata)	API delle risposte	Agenti completi con strumenti ospitati (interprete del codice, ricerca di file, ricerca Web, MCP ospitato)
Completamento conversazione	API di completamento chat	Agenti semplici, supporto generale del modello

Annotazioni

L'API OpenAI Assistants è deprecata da OpenAI. Il nuovo codice deve usare il client Risposte. Se si esegue la migrazione da un'app basata su Assistenti esistente, vedere la guida alla migrazione Kernel semantico.

Come iniziare

Aggiungere i pacchetti NuGet necessari al progetto.

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

Risposte clienti

Il client Risposte è il client primario consigliato e offre il supporto più ricco di strumenti, tra cui interprete del codice, ricerca di file, ricerca Web e MCP ospitato.

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

Strumenti supportati: Strumenti per le funzioni, approvazione degli strumenti, interprete del codice, ricerca di file, ricerca Web, MCP ospitato, strumenti MCP locali.

Cliente per il completamento della chat

Il client Chat Completion offre un modo semplice e diretto per creare agenti tramite l'API Chat Completions. Usalo quando hai bisogno di un'ampia compatibilità con i modelli o se hai già un'integrazione esistente di 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."));

Strumenti supportati: Strumenti per le funzioni, ricerca Web, strumenti MCP locali.

Assistenti del cliente

Annotazioni

L'API OpenAI Assistants è deprecata da OpenAI. Agent Framework non include più la documentazione di un client per Assistants — per il nuovo codice, usa il client Responses indicato sopra. Per la migrazione di un'app esistente, vedere la guida alla migrazione Kernel semantico.

Uso dell'agente

Entrambi i tipi client producono uno standard AIAgent che supporta le stesse operazioni dell'agente (streaming, thread, middleware).

Per altre informazioni, vedere le esercitazioni introduttive.

Tools

I client openAI .NET espongono superfici degli strumenti diverse a seconda dell'API di destinazione. La stessa matrice si applica anche ai client Azure OpenAI corrispondenti nella pagina del provider Azure OpenAI.

Strumento	Responses	Completamento della chat
Strumenti per le funzioni	✅	✅
Approvazione degli strumenti	✅	✅
Interprete di codice	✅	❌
Ricerca file	✅	❌
Ricerca Web	✅	✅
Strumenti MCP ospitati	✅	❌
Strumenti MCP locali	✅	✅

Annotazioni

L'approvazione dello strumento viene fornita dal client di chat di richiamo della funzione del framework, quindi funziona con qualsiasi chiamata dello strumento di funzione indipendentemente dall'API sottostante.

Annotazioni

L'API Degli assistenti OpenAI è deprecata da OpenAI e Python non fornisce più un client/provider di compatibilità Assistants. Usare OpenAIChatClient per le risposte o OpenAIChatCompletionClient per i completamenti della chat. Se si esegue la migrazione da una versione precedente di Agent Framework Python, vedere la guida Python modifiche significative. Se si esegue la migrazione da Kernel semantico, vedere la guida alla migrazione Kernel semantico.

Suggerimento

In Python, Azure OpenAI usa ora gli stessi agent_framework.openai client illustrati qui. Passare esplicitamente input di routing di Azure, come credential o azure_endpoint, quando si desidera utilizzare il routing di Azure, quindi impostare api_version per la superficie API di Azure che si desidera usare. Se OPENAI_API_KEY è configurato, i client generici rimangono in OpenAI anche quando le variabili AZURE_OPENAI_* sono presenti. Se si dispone già di un URL completo .../openai/v1 , usare base_url anziché azure_endpoint. Per gli endpoint del progetto Microsoft Foundry e il servizio Foundry Agent, vedere la pagina del provider Microsoft Foundry. Per i runtime locali, vedere Foundry Local.

Installazione

pip install agent-framework-openai

agent-framework-openai è il pacchetto del provider Python facoltativo per l'utilizzo diretto di OpenAI e OpenAI di Azure.

Impostazione

I client di chat OpenAI Python usano questi modelli di variabili di ambiente:

Risposte

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

Completamento conversazione

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

Azure OpenAI con gli stessi client

Azure OpenAI ora utilizza gli stessi client Python di OpenAI diretti. Il modello di Azure preferito e più chiaro consiste nel passare input espliciti di routing di Azure, credential ad esempio o azure_endpoint, quindi impostare api_version per Azure una volta selezionato il routing. Se OPENAI_API_KEY è impostato, i client generici rimangono in OpenAI a meno che non vengano passati gli input di routing di Azure. Se si dispone AZURE_OPENAI_* solo di impostazioni, il fallback dell'ambiente di Azure funziona ancora. OpenAIChatClient preferisce AZURE_OPENAI_CHAT_MODEL, OpenAIChatCompletionClient preferisce AZURE_OPENAI_CHAT_COMPLETION_MODEL e entrambi ricorrono 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 si dispone già di un URL OpenAI di Azure completo che termina con /openai/v1, passarlo come base_url anziché azure_endpoint. Mantenere api_version allineato alla superficie dell'API di Azure OpenAI che stai utilizzando. Se OPENAI_API_KEY è impostato anche nell'ambiente, questi input espliciti di Azure mantengono il client in Azure.

Annotazioni

Usare OpenAIChatClient per la Responses API. Per l'autenticazione della chiave di Azure, è comunque possibile passare api_key, ma credential= è ora la superficie di autenticazione di Azure preferita.

Incorporamenti di Azure con la stessa famiglia client

OpenAIEmbeddingClient segue le stesse regole di routing dei client di chat. Per gli incorporamenti di Azure, passare la distribuzione dell'incorporamento come model e preferire l'utilizzo di input espliciti di 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(),
)

Creare agenti OpenAI

Risposte

OpenAIChatClient usa l'API Risposte, ovvero il client primario consigliato con supporto per gli strumenti ospitati.

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

Strumenti supportati: Strumenti per le funzioni, approvazione degli strumenti, interprete del codice, ricerca di file, ricerca Web, MCP ospitato, strumenti MCP locali.

Strumenti Ospitati con Client di Risposte

Il client Risposte fornisce get_*_tool() metodi per ogni tipo di strumento ospitato:

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)

Completamento conversazione

OpenAIChatCompletionClient usa l'API Chat Completions: usala quando ti serve un'ampia compatibilità con i modelli o se hai già un'integrazione esistente con 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())

Strumenti supportati: Strumenti per le funzioni, ricerca Web, strumenti MCP locali.

Ricerca Web con completamento della 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

Python non offre più un client/provider di compatibilità Assistants. Per il codice Python attuale, utilizzare OpenAIChatClient per gli scenari dell'API Risposte o OpenAIChatCompletionClient per le completazioni della chat. Se è necessario un agente gestito dal servizio in Microsoft Foundry, vedere la pagina del provider Microsoft Foundry.

Funzionalità comuni

Questi tipi di client supportano queste funzionalità dell'agente standard:

Strumenti per le funzioni

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)

Conversazioni a più turni

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"

Trasmissione in diretta

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

Uso dell'agente

Tutti i tipi di client producono uno standard Agent che supporta le stesse operazioni.

Per altre informazioni, vedere le esercitazioni introduttive.

Tools

I client OpenAI Python espongono superfici degli strumenti diverse a seconda dell'API sottostante. OpenAIChatClient (Risposte) fornisce factory di strumenti ospitati tramite 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 espone solo get_web_search_tool. Entrambi funzionano con gli strumenti per le funzioni e i server MCP locali.

La stessa matrice si applica quando si configurano questi client per Azure OpenAI — vedere Azure OpenAI.

Strumento	OpenAIChatClient (Risposte)	OpenAIChatCompletionClient (Completamento della chat)
Strumenti per le funzioni	✅	✅
Approvazione degli strumenti	✅	✅
Interprete di codice	✅	❌
Ricerca file	✅	❌
Ricerca Web	✅	✅
Generazione di immagini	✅ (get_image_generation_tool)	❌
Shell ospitata	✅ (get_shell_tool)	❌
Strumenti MCP ospitati	✅	❌
Strumenti MCP locali	✅	✅

Annotazioni

L'approvazione dello strumento viene gestita dal client di chat richiamante della funzione del framework, quindi funziona con qualsiasi chiamata di strumento di funzione indipendentemente dall'API sottostante.

Passaggi successivi

Microsoft Foundry