OCI-Antwort-API

Verwenden Sie die Responses-API zusammen mit den folgenden Agent-Building-Komponenten in OCI Generative AI:

Bei Bedarf können Sie die grundlegenden Bausteine der unteren Ebene mit der Responses-API verwenden.

Mit der Antwort-API können Sie:

• Unterstützte gehostete Modelle und importierte Modelle aufrufen.
• Senden Sie Text- und Bildeingaben und empfangen Sie Textausgaben.
• Text oder strukturierte Ausgaben generieren
• Führen Sie Prompts in einem Schritt oder Workflows in mehreren Schritten aus.
• Fügen Sie unterstützte Tools in der Anforderung hinzu.
• Führen Sie längere Anforderungen im Hintergrund aus, und rufen Sie deren Status später ab.
• Streamen Sie Antworten zurück an den Client.
• Verwenden Sie den OCI-verwalteten Unterhaltungsstatus über die Conversations-API.
• Unterhaltungshistorie oder vorherige Ausgaben als Kontext für spätere Anfragen wiederverwenden.
• Verbinden Sie das Modell mit externen Systemen und Daten über Funktionsaufrufe und MCP-Aufrufe.
• Kombinieren Sie Modellanforderungen bei Bedarf mit Dateien, Vektorspeichern oder Containern.

So können Sie mit einer einfachen Eingabeaufforderung beginnen und auf erweiterte Workflows erweitern, ohne zu einer anderen API zu wechseln.

Beginnen Sie bei den meisten neuen Anwendungen mit der Responses-API.

Verwenden Sie es, wenn Sie:

• Verwenden Sie eine API für Modellinteraktionen und Agentikfunktionen.
• Unterstützte Tools zu einer Modellanforderung hinzufügen.
• Verwenden Sie die OCI-verwaltete Unterhaltungshistorie.
• Strukturierte Ausgaben generieren
• Führen Sie Anforderungen aus, ohne die ursprüngliche Verbindung offen zu halten, bis die Generierung abgeschlossen ist.
• Erstellen Sie Workflows, die bei Bedarf auch Dateien, Vektorspeicher oder Container verwenden können.

Ersetzen Sie ${region} durch eine unterstützte Region, wie us-chicago-1.

Obwohl das Anforderungsformat OpenAI-kompatibel ist, verwendet die Authentifizierung OCI-Zugangsdaten, Anforderungen werden über OCI Generative AI-Inferenzendpunkte weitergeleitet, und Ressourcen und Ausführung bleiben in OCI.

Sie können auf zwei Arten auf OCI OpenAI-kompatible Endpunkte zugreifen:

• OCI Generative AI-API-Schlüssel
• OCI IAM-basierte Authentifizierung

Verwenden Sie API-Schlüssel für Tests und frühe Entwicklung. Verwenden Sie die IAM-basierte Authentifizierung für Produktions-Workloads und OCI-verwaltete Umgebungen.

Vor dem Aufrufen der Responses-API:

• Ein OCI Generative AI-Projekt erstellen. OCI OpenAI-kompatible API-Aufrufe erfordern ein Projekt.
• Richten Sie den Client mit der OCI OpenAI-kompatiblen Basis-URL ein.
• Authentifizierung einrichten
• Verwenden Sie ein unterstütztes Modell in einer unterstützten Region.

Einrichtungsschritte finden Sie in der Kurzanleitung, der Authentifizierung und der Unterstützten Modelle und Regionen.

Um die Responses-API aus Code aufzurufen, wird empfohlen, das OpenAI-SDK zu verwenden. Siehe QuickStart.

Im folgenden Beispiel wird das OpenAI-SDK mit dem OCI OpenAI-kompatiblen Endpunkt, einem OCI Generative AI-API-Schlüssel und einer Projekt-OCID verwendet:

from openai import OpenAI

client = OpenAI(
    base_url="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/openai/v1",
    api_key="<your-api-key>", # replace with your Generative AI API Key
    project="ocid1.generativeaiproject.oc1.us-chicago-1.xxxxxxxx",
)

response = client.responses.create(
    model="<supported-model-id>",
    input="Write a one-sentence explanation of what a database is."
)

print(response.output_text)

In diesem Beispiel gilt:

• base_url verweist auf den OCI OpenAI-kompatiblen Endpunkt.
• client.responses.create(...) ruft die OCI-Antwort-API auf.
• project gibt das OCI Generative AI-Projekt für die Anforderung an.

Verwenden Sie den Hintergrundmodus, wenn eine Antwort länger dauern kann, als eine HTTP-Verbindung geöffnet bleiben soll. OCI Generative AI akzeptiert die Anforderung, verarbeitet sie weiter, nachdem der erste Aufruf zurückgegeben wurde, und lässt Ihre Anwendung die Antwort abrufen, bis sie den endgültigen Status erreicht. Der Hintergrundmodus ändert, wie Ihre Anwendung auf das Ergebnis wartet. Dadurch wird die Verarbeitungszeit des Modells nicht verkürzt.

Setzen Sie background auf true, wenn Sie die Antwort erstellen. Speichern Sie die zurückgegebene Antwort-ID, weil Sie sie zum Abrufen oder Abbrechen der Anforderung benötigen.

response = client.responses.create(
    model="<supported-model-id>",
    input="Analyze this incident timeline and propose a prioritized remediation plan.",
    background=True,
)

response_id = response.id
print(f"Response ID: {response_id}")
print(f"Initial status: {response.status}")

from time import sleep

while response.status in {"queued", "in_progress"}:
    sleep(5)
    response = client.responses.retrieve(response_id)
    print(f"Current status: {response.status}")

if response.status == "completed":
    print(response.output_text)
else:
    print(f"Response ended with status: {response.status}")

response = client.responses.cancel(response_id)
print(f"Status: {response.status}")

Um OCI die Multiturn-Unterhaltungshistorie verwalten zu lassen, erstellen Sie zunächst eine Unterhaltung:

conversation = client.conversations.create()

Fügen Sie dann die Unterhaltungs-ID in die Antwort-API-Anforderung ein:

response = client.responses.create(
  model="<supported-model-id>",
  input=[
        {
            "role": "user",
            "content": "Recommend a restaurant based on the food I like."
        }
    ],
    conversation=conversation.id,
)

Verwenden Sie dieses Muster, wenn OCI den Unterhaltungsstatus über Anforderungen hinweg verwalten soll.

Weitere Informationen zu Speicherfunktionen finden Sie unter Conversations API, Short-Term Memory, Long-Term Memory und Short-Term Memory Compaction.

Die Responses-API unterstützt werkzeugfähige Workflows über die Eigenschaft tools. In vielen Anwendungsfällen können Sie die Tools in der Anforderung deklarieren und die Modellausführung und Toolverwendung von OCI Generative AI koordinieren lassen.

Toolunterstützung ist nur über die API verfügbar.

Im folgenden Beispiel wird ein MCP-Tool in der Anforderung definiert:

response = client.responses.create(
    model="openai.gpt-oss-120b",
    tools=[
        {
            "type": "mcp",
            "server_url": "https://example.com/mcp",
        }
    ],
    input="What events are scheduled for 2026-04-02?"
)

In diesem Beispiel ruft die Responses-API das Modell auf und übergibt die MCP-Tooldefinition als Teil derselben Anforderung. Sie benötigen keine separate MCP-spezifische API.

Sie können die grundlegenden Agent-Bausteine mit der Responses-API verwenden, wenn Ihr Workflow eine direkte Kontrolle über Dateien, Vektorspeicher oder Container benötigt.

Häufige Beispiele:

• Dateien vor dem Senden einer Modellanforderung hochladen
• Verwalten von Vektorspeicherinhalten direkt
• Wiederverwendung von Dateien oder Ressourcen über mehrere Anforderungen hinweg
• Arbeiten mit Sandbox-Containern als Teil eines umfassenderen Workflows

Die folgende API wird häufig mit der Responses-API verwendet:

file_response = client.files.create(
    file=open("example-document.pdf", "rb"),
    purpose="assistants"
)

file_id = file_response.id

response = client.responses.create(
    model="<model-id>",
    input=[
        {
            "role": "user",
            "content": [
                { "type": "input_file", "file_id": file_id },
                { "type": "input_text", "text": "List all the cities mentioned in this document." }
            ]
        }
    ]
)

Sie können die OCI-Antworten-API mit dem OpenAI-SDK verwenden. Sie können sie auch mit kompatiblen clientseitigen Agent-Frameworks verwenden.

Das OpenAI SDK unterstützt folgende Sprachen:

• Python
• Java
• TypeScript
• Gehe zu
• .NET

Mehr Sprachunterstützung ist über Community-Bibliotheken verfügbar.

Compatible Agent Frameworks umfassen:

• OpenAI-Agent-SDK (empfohlen)
• OpenAI Codex-SDK
• Microsoft Agent-Framework
• LangChain
• Langgrafik
• TeamKI
• Automatisch generieren
• Lama-Index
• Pydantik

• Unterhaltungs-API
• API-Tools für Antworten
  • Dateisuche
  • Code-Interpreter
  • Funktionsaufrufe
  • MCP - Aufruf
• Datei-API
• Vector Stores-API
• Container-API
• Authentifizierung
  • OCI Generative AI-API-Schlüssel
  • OCI IAM-basierte Authentifizierung
• Unterstützte Modelle und Regionen
• Schnellstart