OCI Responses API

Use the Responses API together with the following agent-building components in OCI Generative AI:

If needed, you can use the low-level foundational building blocks with the Responses API.

Use the Responses API to:

• Call supported hosted models and imported models.
• Send text and image inputs and receive text outputs.
• Generate text or structured outputs.
• Run single-step prompts or multi-step workflows.
• Add supported tools in the request.
• Run longer requests in the background and retrieve their status later.
• Stream responses back to the client.
• Use OCI-managed conversation state through the Conversations API.
• Reuse conversation history or previous outputs as context for later requests.
• Connect the model to external systems and data through Function Calling and MCP Calling.
• Combine model requests with files, vector stores, or containers when needed.

This lets you start with a simple prompt and expand to more advanced workflows without switching to a different API.

For most new applications, start with the Responses API.

Use it when you want to:

• Use one API for model interaction and agentic capabilities.
• Add supported tools to a model request.
• Use OCI-managed conversation history.
• Generate structured outputs.
• Run requests without keeping the original connection open until generation finishes.
• Build workflows that can also use files, vector stores, or containers when needed.

Replace ${region} with a supported region such as us-chicago-1.

Although the request format is OpenAI-compatible, authentication uses OCI credentials, requests are routed through OCI Generative AI inference endpoints, and resources and execution remain in OCI.

You can access OCI OpenAI-compatible endpoints in two ways:

• OCI Generative AI API keys
• OCI IAM-based authentication

Use API keys for testing and early development. Use IAM-based authentication for production workloads and OCI-managed environments.

Before calling the Responses API:

• Create an OCI Generative AI project. OCI OpenAI-compatible API calls require a project.
• Set up the client with the OCI OpenAI-compatible base URL.
• Set up authentication.
• Use a supported model in a supported region.

For setup steps, see QuickStart, Authentication, and Supported Models and Regions.

To call the Responses API from code, we recommend using the OpenAI SDK. See the QuickStart.

The following example uses the OpenAI SDK with the OCI OpenAI-compatible endpoint, an OCI Generative AI API key, and a project OCID:

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 this example:

• base_url points to the OCI OpenAI-compatible endpoint.
• client.responses.create(...) calls the OCI Responses API.
• project identifies the OCI Generative AI project for the request.

Use background mode when a response might take longer than you want to keep an HTTP connection open. OCI Generative AI accepts the request, continues processing it after the initial call returns, and lets your application retrieve the response until it reaches a final status. Background mode changes how your application waits for the result; it doesn't reduce model processing time.

Set background to true when you create the response. Save the returned response ID because you need it to retrieve or cancel the request.

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}")

To let OCI manage multi-turn conversation history, first create a conversation:

conversation = client.conversations.create()

Then include the conversation ID in the Responses API request:

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

Use this pattern when you want OCI to manage conversation state across requests.

For more information about memory capabilities, see Conversations API, Short-Term Memory, Long-Term Memory, and Short-Term Memory Compaction.

The Responses API supports tool-enabled workflows through the tools property. For many use cases, you can declare the tools in the request and let OCI Generative AI coordinate model execution and tool use.

Tool support is available only through the API.

The following example defines an MCP tool in the request:

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 this example, the Responses API invokes the model and passes the MCP tool definition as part of the same request. You don't need a separate MCP-specific API.

You can use the low-level foundational agent building blocks with the Responses API when your workflow needs direct control over files, vector stores, or containers.

Common examples include:

• Uploading files before sending a model request
• Managing vector store contents directly
• Reusing files or resources across multiple requests
• Working with sandbox containers as part of a broader workflow

The following API are commonly used with the Responses API:

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." }
            ]
        }
    ]
)

You can use the OCI Responses API with the OpenAI SDK. You can also use it with compatible client-side agent frameworks.

The OpenAI SDK supports these languages:

• Python
• Java
• TypeScript
• Go
• .NET

More language support is available through community libraries.

Compatible agent frameworks include:

• OpenAI Agents SDK (recommended)
• OpenAI Codex SDK
• Microsoft Agent Framework
• LangChain
• LangGraph
• CrewAI
• AutoGen
• LlamaIndex
• Pydantic

• Conversations API
• Responses API Tools
  • File Search
  • Code Interpreter
  • Function Calling
  • MCP Calling
• Files API
• Vector Stores API
• Containers API
• Authentication
  • OCI Generative AI API keys
  • OCI IAM-based authentication
• Supported Models and Regions
• QuickStart