autogen_ext.agents.openai#

class OpenAIAgent(name: str, description: str, client: AsyncOpenAI | AsyncAzureOpenAI, model: str, instructions: str, tools: Iterable[Literal['web_search_preview', 'image_generation', 'local_shell'] | FileSearchToolConfig | WebSearchToolConfig | ComputerUseToolConfig | MCPToolConfig | CodeInterpreterToolConfig | ImageGenerationToolConfig | LocalShellToolConfig] | None = None, temperature: float | None = 1, max_output_tokens: int | None = None, json_mode: bool = False, store: bool = True, truncation: str = 'disabled')[source]#

Bases: BaseChatAgent, Component[OpenAIAgentConfig]

Eine Agentenimplementierung, die die OpenAI Responses API zur Generierung von Antworten verwendet.

Installation

pip install "autogen-ext[openai]"
# pip install "autogen-ext[openai,azure]"  # For Azure OpenAI Assistant

Dieser Agent nutzt die Responses API zur Generierung von Antworten mit Funktionen wie

  • Mehrfach-Runden-Gespräche

  • Integrierte Tool-Unterstützung (file_search, code_interpreter, web_search_preview, etc.)

Derzeit werden benutzerdefinierte Tools nicht unterstützt.

Geändert in Version v0.7.0: Unterstützung für integrierte Tool-Typen wie file_search, web_search_preview, code_interpreter, computer_use_preview, image_generation und mcp hinzugefügt. Unterstützung für Tool-Konfigurationen mit erforderlichen und optionalen Parametern hinzugefügt.

Integrierte Tools sind in zwei Kategorien unterteilt

Tools, die das String-Format verwenden können (keine erforderlichen Parameter)

  • web_search_preview: Kann als "web_search_preview" oder mit optionaler Konfiguration (user_location, search_context_size) verwendet werden

  • image_generation: Kann als "image_generation" oder mit optionaler Konfiguration (background, input_image_mask) verwendet werden

  • local_shell: Kann als "local_shell" verwendet werden (WARNUNG: Funktioniert nur mit dem codex-mini-latest Modell)

Tools, die eine Dict-Konfiguration ERFORDERN (haben erforderliche Parameter)

  • file_search: MUSS ein Dict mit vector_store_ids (List[str]) verwenden

  • computer_use_preview: MUSS ein Dict mit display_height (int), display_width (int), environment (str) verwenden

  • code_interpreter: MUSS ein Dict mit container (str) verwenden

  • mcp: MUSS ein Dict mit server_label (str), server_url (str) verwenden

Die Verwendung von Tools mit erforderlichen Parametern im String-Format löst einen ValueError mit hilfreichen Fehlermeldungen aus. Die Typannotation für den Parameter 'tools' akzeptiert nur String-Werte für Tools, die keine Parameter erfordern.

Hinweis

Benutzerdefinierte Tools (autogen FunctionTool oder andere vom Benutzer definierte Tools) werden von diesem Agenten nicht unterstützt. Es werden nur die integrierten OpenAI-Tools unterstützt, die über die Responses API bereitgestellt werden.

Parameter:

  • name (str) – Name des Agenten

  • description (str) – Beschreibung des Zwecks des Agenten

  • client (Union[AsyncOpenAI, AsyncAzureOpenAI]) – OpenAI-Client-Instanz

  • model (str) – Zu verwendendes Modell (z. B. "gpt-4.1")

  • instructions (str) – Systemanweisungen für den Agenten

  • tools (Optional[Iterable[Union[str, BuiltinToolConfig]]]) – Tools, die der Agent verwenden kann. Unterstützte String-Werte (keine erforderlichen Parameter): "web_search_preview", "image_generation", "local_shell". Dict-Werte können Konfigurationen für integrierte Tools mit Parametern bereitstellen. Erforderliche Parameter für integrierte Tools: - file_search: vector_store_ids (List[str]) - computer_use_preview: display_height (int), display_width (int), environment (str) - code_interpreter: container (str) - mcp: server_label (str), server_url (str) Optionale Parameter für integrierte Tools: - file_search: max_num_results (int), ranking_options (dict), filters (dict) - web_search_preview: user_location (str oder dict), search_context_size (int) - image_generation: background (str), input_image_mask (str) - mcp: allowed_tools (List[str]), headers (dict), require_approval (bool) Spezielle Tools mit Modellbeschränkungen: - local_shell: Funktioniert nur mit dem Modell "codex-mini-latest" (WARNUNG: Sehr eingeschränkte Unterstützung) Benutzerdefinierte Tools werden nicht unterstützt.

  • temperature (Optional[float]) – Temperatur für die Antwortgenerierung (Standard: 1)

  • max_output_tokens (Optional[int]) – Maximale Ausgabetokens

  • json_mode (bool) – Ob der JSON-Modus verwendet werden soll (Standard: False)

  • store (bool) – Ob Konversationen gespeichert werden sollen (Standard: True)

  • truncation (str) – Trunkierungsstrategie (Standard: "disabled")

Beispiel

Grundlegende Verwendung mit integrierten Tools

import asyncio

from autogen_agentchat.ui import Console
from autogen_ext.agents.openai import OpenAIAgent
from openai import AsyncOpenAI


async def example():
    client = AsyncOpenAI()
    agent = OpenAIAgent(
        name="SimpleAgent",
        description="A simple OpenAI agent using the Responses API",
        client=client,
        model="gpt-4.1",
        instructions="You are a helpful assistant.",
        tools=["web_search_preview"],  # Only tools without required params
    )
    await Console(agent.run_stream(task="Search for recent AI developments"))


asyncio.run(example())

Verwendung mit konfigurierten integrierten Tools

import asyncio

from autogen_agentchat.ui import Console
from autogen_ext.agents.openai import OpenAIAgent
from openai import AsyncOpenAI


async def example_with_configs():
    client = AsyncOpenAI()
    # Configure tools with required and optional parameters
    tools = [
        # {
        #     "type": "file_search",
        #     "vector_store_ids": ["vs_abc123"],  # required
        #     "max_num_results": 10,  # optional
        # },
        # {
        #     "type": "computer_use_preview",
        #     "display_height": 1024,  # required
        #     "display_width": 1280,  # required
        #     "environment": "linux",  # required
        # },
        {
            "type": "code_interpreter",
            "container": {"type": "auto"},  # required
        },
        # {
        #     "type": "mcp",
        #     "server_label": "my-mcp-server",  # required
        #     "server_url": "https://:3000",  # required
        # },
        {
            "type": "web_search_preview",
            "user_location": {  # optional - structured location
                "type": "approximate",  # required: "approximate" or "exact"
                "country": "US",  # optional
                "region": "CA",  # optional
                "city": "San Francisco",  # optional
            },
            "search_context_size": "low",  # optional
        },
        # "image_generation",  # Simple tools can still use string format
    ]

    agent = OpenAIAgent(
        name="ConfiguredAgent",
        description="An agent with configured tools",
        client=client,
        model="gpt-4.1",
        instructions="You are a helpful assistant with specialized tools.",
        tools=tools,  # type: ignore
    )
    await Console(agent.run_stream(task="Search for recent AI developments"))


asyncio.run(example_with_configs())
Hinweis

Benutzerdefinierte Tools werden von OpenAIAgent nicht unterstützt. Verwenden Sie nur integrierte Tools aus der Responses API.

component_config_schema#

alias von OpenAIAgentConfig

component_provider_override: ClassVar[str | None] = 'autogen_ext.agents.openai.OpenAIAgent'#

Überschreibe den Anbieter-String für die Komponente. Dies sollte verwendet werden, um zu verhindern, dass interne Modulnamen Teil des Modulnamens werden.

property produced_message_types: Sequence[Type[TextMessage] | Type[MultiModalMessage] | Type[StopMessage] | Type[ToolCallSummaryMessage] | Type[HandoffMessage]]#

Gibt die Nachrichtentypen zurück, die dieser Agent erzeugen kann.

async on_messages(messages: Sequence[BaseChatMessage], cancellation_token: CancellationToken) → Response[source]#

Verarbeitet eingehende Nachrichten und gibt eine Antwort zurück.

Hinweis

Agenten sind zustandsbehaftet, und die an diese Methode übergebenen Nachrichten sollten die neuen Nachrichten seit dem letzten Aufruf dieser Methode sein. Der Agent sollte seinen Zustand zwischen den Aufrufen dieser Methode beibehalten. Wenn der Agent sich beispielsweise die vorherigen Nachrichten merken muss, um auf die aktuelle Nachricht zu reagieren, sollte er die vorherigen Nachrichten im Agentenzustand speichern.

async on_messages_stream(messages: Sequence[BaseChatMessage], cancellation_token: CancellationToken) → AsyncGenerator[Annotated[ToolCallRequestEvent | ToolCallExecutionEvent | MemoryQueryEvent | UserInputRequestedEvent | ModelClientStreamingChunkEvent | ThoughtEvent | SelectSpeakerEvent | CodeGenerationEvent | CodeExecutionEvent, FieldInfo(annotation=NoneType, required=True, discriminator='type')] | TextMessage | MultiModalMessage | StopMessage | ToolCallSummaryMessage | HandoffMessage | Response, None][source]#

Verarbeitet eingehende Nachrichten und gibt einen Stream von Nachrichten zurück, wobei das letzte Element die Antwort ist. Die Basisimplementierung in BaseChatAgent ruft einfach on_messages() auf und gibt die Nachrichten in der Antwort aus.

Hinweis

Agenten sind zustandsbehaftet, und die an diese Methode übergebenen Nachrichten sollten die neuen Nachrichten seit dem letzten Aufruf dieser Methode sein. Der Agent sollte seinen Zustand zwischen den Aufrufen dieser Methode beibehalten. Wenn der Agent sich beispielsweise die vorherigen Nachrichten merken muss, um auf die aktuelle Nachricht zu reagieren, sollte er die vorherigen Nachrichten im Agentenzustand speichern.

async on_reset(cancellation_token: CancellationToken) → None[source]#

Setzt den Agenten in seinen Initialzustand zurück.

async save_state() → Mapping[str, Any][source]#

Exportiert den Zustand. Standardimplementierung für zustandslose Agenten.

async load_state(state: Mapping[str, Any]) → None[source]#

Stellt den Agenten aus dem gespeicherten Zustand wieder her. Standardimplementierung für zustandslose Agenten.

to_config() → OpenAIAgentConfig[source]#

Öffentliche Wrapper-Methode für die private _to_config-Methode.

classmethod from_config(config: OpenAIAgentConfig) → OpenAIAgent[source]#

Öffentlicher Wrapper für die private Klassenmethode _from_config.

property tools: list[Any]#

Öffentlicher Zugriff auf die Tools des Agenten.

property model: str#

Öffentlicher Zugriff auf das Modell des Agenten.

class OpenAIAssistantAgent(name: str, description: str, client: AsyncOpenAI | AsyncAzureOpenAI, model: str, instructions: str, tools: Iterable[Literal['code_interpreter', 'file_search'] | Tool | Callable[[...], Any] | Callable[[...], Awaitable[Any]]] | None = None, assistant_id: str | None = None, thread_id: str | None = None, metadata: Dict[str, str] | None = None, response_format: Literal['auto'] | ResponseFormatText | ResponseFormatJSONObject | ResponseFormatJSONSchema | None = None, temperature: float | None = None, tool_resources: ToolResources | None = None, top_p: float | None = None)[source]#

Bases: BaseChatAgent

Ein Agent, der die Assistant API verwendet, um Antworten zu generieren.

Installation

pip install "autogen-ext[openai]"  # For OpenAI Assistant
# pip install "autogen-ext[openai,azure]"  # For Azure OpenAI Assistant

Dieser Agent nutzt die Assistant API, um KI-Assistenten mit Fähigkeiten wie

  • Codeinterpretation und -ausführung

  • Datei-Handling und -Suche

  • Benutzerdefinierte Funktionsaufrufe

  • Mehrfach-Runden-Gespräche

Der Agent verwaltet einen Gesprächsfaden und kann verschiedene Werkzeuge nutzen, darunter

  • Code-Interpreter: Zur Ausführung von Code und zur Arbeit mit Dateien

  • Datei-Suche: Zur Suche in hochgeladenen Dokumenten

  • Benutzerdefinierte Funktionen: Zur Erweiterung der Fähigkeiten mit benutzerdefinierten Werkzeugen

Hauptmerkmale

  • Unterstützt mehrere Dateiformate, einschließlich Code, Dokumenten und Bildern

  • Kann bis zu 128 Werkzeuge pro Assistent verwalten

  • Verwaltet den Gesprächskontext in Threads

  • Unterstützt Datei-Uploads für Code-Interpreter und Suche

  • Vektor-Store-Integration für effiziente Dateisuche

  • Automatische Dateianalyse und Einbettung

Sie können einen vorhandenen Thread oder Assistenten verwenden, indem Sie die Parameter thread_id oder assistant_id angeben.

Examples

Verwenden Sie den Assistenten, um Daten in einer CSV-Datei zu analysieren

from openai import AsyncOpenAI
from autogen_core import CancellationToken
import asyncio
from autogen_ext.agents.openai import OpenAIAssistantAgent
from autogen_agentchat.messages import TextMessage


async def example():
    cancellation_token = CancellationToken()

    # Create an OpenAI client
    client = AsyncOpenAI(api_key="your-api-key", base_url="your-base-url")

    # Create an assistant with code interpreter
    assistant = OpenAIAssistantAgent(
        name="PythonHelper",
        description="Helps with Python programming",
        client=client,
        model="gpt-4",
        instructions="You are a helpful Python programming assistant.",
        tools=["code_interpreter"],
    )

    # Upload files for the assistant to use
    await assistant.on_upload_for_code_interpreter("data.csv", cancellation_token)

    # Get response from the assistant
    response = await assistant.on_messages(
        [TextMessage(source="user", content="Analyze the data in data.csv")], cancellation_token
    )

    print(response)

    # Clean up resources
    await assistant.delete_uploaded_files(cancellation_token)
    await assistant.delete_assistant(cancellation_token)


asyncio.run(example())

Verwenden Sie den Azure OpenAI Assistant mit AAD-Authentifizierung

from openai import AsyncAzureOpenAI
import asyncio
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from autogen_core import CancellationToken
from autogen_ext.agents.openai import OpenAIAssistantAgent
from autogen_agentchat.messages import TextMessage


async def example():
    cancellation_token = CancellationToken()

    # Create an Azure OpenAI client
    token_provider = get_bearer_token_provider(DefaultAzureCredential())
    client = AsyncAzureOpenAI(
        azure_deployment="YOUR_AZURE_DEPLOYMENT",
        api_version="YOUR_API_VERSION",
        azure_endpoint="YOUR_AZURE_ENDPOINT",
        azure_ad_token_provider=token_provider,
    )

    # Create an assistant with code interpreter
    assistant = OpenAIAssistantAgent(
        name="PythonHelper",
        description="Helps with Python programming",
        client=client,
        model="gpt-4o",
        instructions="You are a helpful Python programming assistant.",
        tools=["code_interpreter"],
    )

    # Get response from the assistant
    response = await assistant.on_messages([TextMessage(source="user", content="Hello.")], cancellation_token)

    print(response)

    # Clean up resources
    await assistant.delete_assistant(cancellation_token)


asyncio.run(example())
Parameter:

  • name (str) – Name des Assistenten

  • description (str) – Beschreibung des Zwecks des Assistenten

  • client (AsyncOpenAI | AsyncAzureOpenAI) – Instanz des OpenAI-Clients oder Azure OpenAI-Clients

  • model (str) – Zu verwendendes Modell (z. B. „gpt-4“)

  • instructions (str) – Systemanweisungen für den Assistenten

  • tools (Optional[Iterable[Union[Literal["code_interpreter", "file_search"], Tool | Callable[..., Any] | Callable[..., Awaitable[Any]]]]) – Werkzeuge, die der Assistent verwenden kann

  • assistant_id (Optional[str]) – ID eines vorhandenen Assistenten, der verwendet werden soll

  • thread_id (Optional[str]) – ID eines vorhandenen Threads, der verwendet werden soll

  • metadata (Optional[Dict[str, str]]) – Zusätzliche Metadaten für den Assistenten.

  • response_format (Optional[AssistantResponseFormatOptionParam]) – Einstellungen für das Antwortformat

  • temperature (Optional[float]) – Temperatur für die Antwortgenerierung

  • tool_resources (Optional[ToolResources]) – Zusätzliche Werkzeugkonfiguration

  • top_p (Optional[float]) – Top-p-Sampling-Parameter

property produced_message_types: Sequence[type[BaseChatMessage]]#

Die von diesem Agenten erzeugten Nachrichtentypen.

property threads: AsyncThreads#
property runs: AsyncRuns#
property messages: AsyncMessages#
async on_messages(messages: Sequence[BaseChatMessage], cancellation_token: CancellationToken) → Response[source]#

Behandelt eingehende Nachrichten und gibt eine Antwort zurück.

async on_messages_stream(messages: Sequence[BaseChatMessage], cancellation_token: CancellationToken) → AsyncGenerator[BaseAgentEvent | BaseChatMessage | Response, None][source]#

Behandelt eingehende Nachrichten und gibt eine Antwort zurück.

async handle_incoming_message(message: BaseChatMessage, cancellation_token: CancellationToken) → None[source]#

Behandelt reguläre Textnachrichten, indem sie dem Thread hinzugefügt werden.

async on_reset(cancellation_token: CancellationToken) → None[source]#

Behandelt den Reset-Befehl, indem neue Nachrichten und Läufe seit der Initialisierung gelöscht werden.

async on_upload_for_code_interpreter(file_paths: str | Iterable[str], cancellation_token: CancellationToken) → None[source]#

Behandelt Datei-Uploads für den Code-Interpreter.

Behandelt Datei-Uploads für die Dateisuche.

async delete_uploaded_files(cancellation_token: CancellationToken) → None[source]#

Löscht alle Dateien, die von dieser Agenteninstanz hochgeladen wurden.

async delete_assistant(cancellation_token: CancellationToken) → None[source]#

Löscht den Assistenten, wenn er von dieser Instanz erstellt wurde.

async delete_vector_store(cancellation_token: CancellationToken) → None[source]#

Löscht den Vektor-Store, wenn er von dieser Instanz erstellt wurde.

async save_state() → Mapping[str, Any][source]#

Exportiert den Zustand. Standardimplementierung für zustandslose Agenten.

async load_state(state: Mapping[str, Any]) → None[source]#

Stellt den Agenten aus dem gespeicherten Zustand wieder her. Standardimplementierung für zustandslose Agenten.