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.
• 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.
• Build workflows that can also use files, vector stores, or containers when needed.

Replace ${region} with a supported OCI 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="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    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.

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