QuickStart

Before you create a project or call the OCI Responses API, ensure that the required IAM permissions are in place.

The OCI Responses API supports two authentication methods. You can use either option.

• OCI Generative AI API keys

  Authenticate and reach the models and endpoints with OpenAI-compatible Generative AI service-specific API keys. Use this option for testing and early development.

• OCI IAM-based authentication

  Authenticate and reach the models and endpoints by using signed API requests. We recommend this option for production workloads and OCI-managed environments. Consider using IAM authentication when you:

  • Run applications in OCI services such as Functions or Oracle Kubernetes Engine (OKE)
  • Want to avoid long-lived API keys
  • Need centralized access control through OCI IAM

Install the Official OpenAI SDK.

Python

pip install openai

For other languages, see the OpenAI libraries page.

The OCI Responses API is the primary API for building Enterprise AI agentic applications in OCI Generative AI. It lets you send model requests, use tools, and manage conversation context through a single API.

Use the Responses API to:

• Run simple, single-step inference or multi-step agent workflows
• Enable or disable reasoning, depending on the use case
• Integrate platform-managed or client-side tools
• Manage conversation state either in the service or in the client

The OCI Responses API uses an OpenAI-compatible interface. Requests use the same OpenAI-style syntax, but they're sent to OCI Generative AI and authenticated with OCI credentials, such as OCI Generative AI API keys or OCI IAM-based authentication.

The recommended client is the OpenAI SDK. It supports languages such as Python, Java, TypeScript, Go, and .NET. You can also use it with frameworks such as LangChain, LlamaIndex, and OpenAI Agents SDK.

Use the following base URL:

Base URL: https://inference.generativeai.${region}.oci.oraclecloud.com/openai/v1

Replace ${region} with your OCI region, for example, us-chicago-1.

For the Responses API, use the following endpoint path:

/responses

You can use the OCI Responses API to call different types of models available in OCI Generative AI supported regions. For a list of supported models and regions, see Agent Models and Regions.

response = client.responses.create(
    model="xai.grok-4-1-fast-reasoning",
    input="Write a one-sentence explanation of what a database is."
)

response = client.responses.create(
    model="google.gemini-2.5-pro",
    input="Write a one-sentence explanation of what a database is."
)

response = client.responses.create(
    model="<dedicated-ai-cluster-endpoint-ocid>",
    input="Write a one-sentence explanation of what a database is."
)

Select a model in an available region, with the available mode that best fits your requirements for performance, cost, and control.

The following examples shows how to call the Responses API by using Python. If the request returns an explanation, the OCI Responses API is working correctly.

If you encounter issues when calling the API, enabling debug logging can help with troubleshooting. Debug logs display the raw HTTP requests and responses, including the opc-request-id, which is useful when working with Oracle support.

You can reference this request ID when reporting issues to help identify and diagnose problems more quickly.

from openai import OpenAI
import logging

logger = logging.getLogger("openai")
logger.setLevel(logging.DEBUG)
logger.addHandler(logging.StreamHandler())

# Create and use the OpenAI client as usual
client = OpenAI(
    ...
)

The OCI Responses API supports streaming, where you can receive model outputs incrementally as the tokens are generated.

response_stream = client.responses.create(
    model="openai.gpt-oss-120b",
    input="Explain the difference between structured and unstructured data.",
    stream=True
)

for event in response_stream:
    print(event)

response_stream = client.responses.create(
    model="openai.gpt-oss-120b",
    input="Explain the difference between structured and unstructured data.",
    stream=True
)

for event in response_stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

Reasoning controls let you tune how much effort the model uses before producing a response. This is useful when you want to prioritize speed, depth, or a balance of both.

response = client.responses.create(
    model="openai.gpt-oss-120b",
    input="Solve 18 * (4 + 2).",
    reasoning={"effort": "medium"},
    store=False,
)

print(response.output_text)

response = client.responses.create(
    model="openai.gpt-oss-120b",
    input="Solve 18 * (4 + 2).",
    reasoning={"summary": "auto"},
    store=False,
)

print(response.output_text)

Use structured outputs when you want the model to return data in a predictable format instead of free-form text. This is useful for extracting fields from unstructured input, passing results to other systems, or showing specific values in a UI. In the OCI Responses API, you define a schema and parse the response against it, which makes the output more consistent and easier for applications to use. Structured outputs match a supplied schema, while a JSON mode only guarantees valid JSON.

A strongly typed object is an object whose fields and data types are defined in advance. For example, if a schema says customer_name must be a string and priority must be one of "low", "medium", or "high", the parsed result follows that structure. This makes it easier for code to work with the response safely and predictably. The OCI Responses API supports this by allowing you to define a schema and parse the model output into strongly typed objects.

This approach is useful when integrating with downstream systems, enforcing consistency, or extracting specific fields from natural language input.

from pydantic import BaseModel
from typing import Literal

class SupportRequest(BaseModel):
    customer_name: str
    product: str
    issue_summary: str
    priority: Literal["low", "medium", "high"]
    requested_action: str

response = client.responses.parse(
    model="<supported-model-id>",
    input=[
        {"role": "system", "content": "Extract the support request into the schema."},
        {
            "role": "user",
            "content": (
                "Sarah Johnson from Example Company says the mobile inventory app "
                "crashes whenever she scans more than 20 items in one session. "
                "This is delaying warehouse processing, and she wants a fix as soon as possible."
            ),
        },
    ],
    text_format=SupportRequest,
)

support_request = response.output_parsed
print(support_request)

Example output:

SupportRequest(
customer_name='Sarah Johnson', 
product='mobile inventory app', 
issue_summary='App crashes whenever she scans more than 20 items in one session.', 
priority='high', 
requested_action='Provide a fix as soon as possible'
)

The OCI Responses API supports models that accept multimodal inputs. You can combine text with images, files, and reasoning controls to support richer workflows such as document analysis, image understanding, and more deliberate model responses.

import base64

def encode_image(image_path):
    with open(image_path, "rb") as image_file:
        return base64.b64encode(image_file.read()).decode("utf-8")

base64_image = encode_image("/path/to/image.png")

response = client.responses.create(
    model="google.gemini-2.5-pro",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "Describe the main objects in this image."},
                {
                    "type": "input_image",
                    "image_url": f"data:image/jpeg;base64,{base64_image}",
                    "detail": "high",
                },
            ],
        }
    ],
)

print(response.output_text)

response = client.responses.create(
    model="google.gemini-2.5-pro",
    store=False,
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "Describe the scene shown in this image."},
                {
                    "type": "input_image",
                    "image_url": "https://example.photos/id/123",
                },
            ],
        }
    ],
)

print(response.output_text)

file = client.files.create(
    file=open("<path-to-file>", "rb"),
    purpose="user_data"
)

response = client.responses.create(
    model="google.gemini-2.5-pro",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_file",
                    "file_id": file.id,
                },
                {
                    "type": "input_text",
                    "text": "Summarize this document.",
                },
            ]
        }
    ]
)

print(response.output_text)

response = client.responses.create(
    model="google.gemini-2.5-flash",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "Summarize this file."},
                {
                    "type": "input_file",
                    "file_url": "https://www.example.com/letters/example-letter.pdf",
                },
            ],
        }
    ],
)

print(response.output_text)

Use File Search to let the model retrieve relevant content from files stored in a vector store during response generation. This is useful when you want responses to reflect the documents you provide rather than relying only on the model’s built-in knowledge.

By creating vector stores and adding files to them, you enable semantic and keyword-based search across your data. This extends the model’s built-in knowledge with your custom content and helps produce more precise, context-aware answers.

Because File Search is handled by the service, your application doesn't need to implement its own retrieval pipeline.

response = client.responses.create(
    model="openai.gpt-oss-120b",
    input="Summarize the main ideas covered in the documents in this vector store.",
    tools=[
        {
            "type": "file_search",
            "vector_store_ids": ["<vector_store_id>"]
        }
    ]
)

print(response)

Use Code Interpreter to let the model write and run Python code in a secure, isolated container. This tool is useful for calculations, data analysis, file processing, and other computation-heavy tasks.

Because code runs in an isolated environment with no external network access, Code Interpreter is a good option when the workflow needs computation or file processing in a controlled setting.

Use Function Calling to let the model request data or actions from your application during a Responses API workflow. This is useful when the model needs information or operations that aren't available in the prompt itself, such as calendar data, internal application state, or the result of a custom operation.

With this pattern, the model doesn't execute the function directly. Instead, it returns the function name and arguments, your application runs the function, and then your application sends the function output back so the model can continue and produce the user-facing answer.

tools = [
    {
        "type": "function",
        "name": "get_calendar_events",
        "description": "Return calendar events scheduled for a specific date.",
        "parameters": {
            "type": "object",
            "properties": {
                "date": {
                    "type": "string",
                    "description": "Date to query, for example 2026-04-02"
                }
            },
            "required": ["date"],
        },
    },
]

import json

tools = [
    {
        "type": "function",
        "name": "get_calendar_events",
        "description": "Return calendar events scheduled for a specific date.",
        "parameters": {
            "type": "object",
            "properties": {
                "date": {
                    "type": "string",
                    "description": "Date to query, for example 2026-04-02"
                }
            },
            "required": ["date"],
        },
    },
]

def get_calendar_events(date):
    # Replace this with actual calendar logic or an API call
    return [
        {"time": "09:00", "title": "Team standup"},
        {"time": "13:00", "title": "Design review"},
        {"time": "16:00", "title": "Project check-in"},
    ]

# Initial request
response = client.responses.create(
    model="openai.gpt-oss-120b",
    tools=tools,
    input="Show the calendar events for 2026-04-02.",
)

# Execute the requested function
tool_outputs = []
for item in response.output:
    if item.type == "function_call" and item.name == "get_calendar_events":
        args = json.loads(item.arguments)
        events = get_calendar_events(**args)
        tool_outputs.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": json.dumps({"events": events}),
        })

# Follow-up request
final = client.responses.create(
    model="openai.gpt-oss-120b",
    instructions="Summarize the schedule clearly for the user.",
    tools=tools,
    input=tool_outputs,
    previous_response_id=response.id,
)

print(final.output_text)

import json

tools = [
    {
        "type": "function",
        "name": "get_calendar_events",
        "description": "Return calendar events scheduled for a specific date.",
        "parameters": {
            "type": "object",
            "properties": {
                "date": {
                    "type": "string",
                    "description": "Date to query, for example 2026-04-02"
                }
            },
            "required": ["date"],
        },
    },
]

def get_calendar_events(date):
    # Replace this with actual calendar logic or an API call
    return [
        {"time": "09:00", "title": "Team standup"},
        {"time": "13:00", "title": "Design review"},
        {"time": "16:00", "title": "Project check-in"},
    ]

conversation = [
    {"role": "user", "content": "Show the calendar events for 2026-04-02."}
]

response = client.responses.create(
    model="openai.gpt-oss-120b",
    tools=tools,
    input=conversation,
)

conversation += response.output

for item in response.output:
    if item.type == "function_call" and item.name == "get_calendar_events":
        args = json.loads(item.arguments)
        events = get_calendar_events(**args)
        conversation.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": json.dumps({"events": events}),
        })

final = client.responses.create(
    model="openai.gpt-oss-120b",
    instructions="Summarize the schedule clearly for the user.",
    tools=tools,
    input=conversation,
)

print(final.output_text)

MCP (Model Context Protocol) tools are executable functions or capabilities that AI models can use to interact with external systems. Use MCP Calling in OCI Generative AI to let a model access executable tools exposed by a remote MCP server during a Responses API request. These tools can provide access to external systems such as API, databases, file systems, or application endpoints. OCI Generative AI communicates directly with remote MCP servers as part of the request workflow.

Use SQL Search (NL2SQL) to convert natural-language requests into validated SQL for enterprise data in OCI Generative AI.

NL2SQL helps Enterprise AI Agents work with federated enterprise data without moving or duplicating the underlying data. It uses a semantic enrichment layer to map business terms to database tables, columns, and joins, and then generates SQL from natural-language input.

NL2SQL generates SQL only. It doesn't run the query itself. Query execution is handled separately through the DBTools MCP Server, which authorizes and runs the query against the source database by using the end user’s identity and the appropriate guardrails.

Before you use NL2SQL, you must have:

• A source database, such as Oracle Autonomous Database
• Two DBTools connections:
  • Enrichment Connection
  • Query Connection
• IAM permissions for Semantic Stores, NL2SQL, Database Tools, and secrets
• OCI IAM authentication configured for the OCI service APIs used in this quickstart

Before you create a Semantic Store, create the source database and the required DBTools connections.

You need the following connections:

Before you create a Semantic Store, set up the required IAM policies.

This QuickStart uses OCI IAM authentication for the OCI service API that create Semantic Stores, run enrichment jobs, and generate SQL.

Set up OCI IAM authentication for the identity that signs requests. The examples in this section use the OCI Python SDK and BaseClient.

You can authenticate by using:

• An OCI config file and API signing keys
• A security token signer

The following examples use SecurityTokenSigner, but you can also use a standard OCI config signer if that fits your environment better.

Related Topics

• SDK and CLI Configuration File
• Request Signatures
• Signer Python SDK

For Automation, if you selected None instead of On create, you can run enrichment after the semantic store is created. Perform this step if you skipped the On create option.

The enrichment process reads schema metadata, such as tables and columns, from the connected database. OCI Generative AI uses this metadata to help generate the SQL.

To trigger enrichment manually, call the GenerateEnrichmentJob API.

You can also manage enrichment jobs by using the following API:

• ListEnrichmentJobs
• GetEnrichmentJob
• CancelEnrichmentJob

NL2SQL uses OCI service APIs rather than the OCI OpenAI-compatible /openai/v1 paths.

After the Semantic Store is ready and enrichment has completed, call the NL2SQL API to generate SQL from natural language.

import json
import oci
from oci.base_client import BaseClient

INFERENCE_BASE_URL = "https://inference.generativeai.<region>.oci.oraclecloud.com"
API_VERSION = "20260325"
SEMANTIC_STORE_ID = "ocid1.generativeaisemanticstore.oc1.xxx"

config = oci.config.from_file("~/.oci/config", "oc1")
signer = oci.auth.signers.SecurityTokenSigner(config)

client = BaseClient(
    service_endpoint=INFERENCE_BASE_URL,
    signer=signer,
    retry_strategy=None,
)

resource_path = (
    f"/{API_VERSION}/semanticStores/{SEMANTIC_STORE_ID}/actions/generateSqlFromNl"
)

body = {
    "displayName": "Generate SQL example",
    "description": "Generate SQL from natural language",
    "inputNaturalLanguageQuery": "Give me last week's order details."
}

resp = client.call_api(
    resource_path=resource_path,
    method="POST",
    header_params={"content-type": "application/json"},
    body=body,
)

print("HTTP status:", resp.status)
print("opc-request-id:", resp.headers.get("opc-request-id"))

data = resp.data
if isinstance(data, (bytes, str)):
    data = json.loads(data)

print(json.dumps(data, indent=2))

Use the built-in response trace data in the OCI Responses API to understand how a request was processed. For deeper observability, you can also integrate the OCI Responses API with external observability platforms such as Langfuse.

This QuickStart shows how to inspect execution details returned by the Responses API and how to trace requests by using Langfuse.

Before you begin, you must have:

• An OCI Generative AI project
• Authentication configured for the OCI Responses API
• The OpenAI SDK installed
• A working OCI Responses API client

(Optional) To integrate with Langfuse, you need a Langfuse account and credentials.

When you call the OCI Responses API, the response includes an output field. This field is an array of items that describe what occurred during the request.

Each item represents a step in the execution and can include different types, such as:

• message
• file_search_call
• mcp_call

These output items provide visibility into how the request was processed. You can use them to:

• Debug and understand model behavior
• Display execution steps in a user interface
• Build custom observability or logging workflows

For example, after you send a request, you can inspect the output field:

response = client.responses.create(
    model="openai.gpt-oss-120b",
    input="Explain the difference between structured and unstructured data."
)

for item in response.output:
    print(item.type)

For deeper insight, such as latency, cost, and execution traces, you can integrate the OCI Responses API with an observability platform.

One option is Langfuse, an open-source LLM engineering platform that helps developers debug, monitor, and improve LLM applications. Langfuse provides end-to-end observability for tracing agent actions, supports prompt versioning, and helps evaluate model outputs. It integrates with popular frameworks such as OpenAI, LangChain, and LlamaIndex.

Install the Langfuse SDK:

pip install langfuse

Set the required Langfuse and OCI environment variables:

LANGFUSE_SECRET_KEY="sk-lf-xxxxxxxxx"
LANGFUSE_PUBLIC_KEY="pk-lf-xxxxxxxxx"
LANGFUSE_BASE_URL="https://us.cloud.langfuse.com"

# OCI Generative AI credentials
OCI_GENAI_API_KEY="sk-xxxxxxxxx"
OCI_GENAI_PROJECT_ID="ocid1.generativeaiproject.oc1.xxx"

Import the OpenAI client from the Langfuse SDK. The existing request code stays the same, but requests are automatically traced.

import os
from langfuse.openai import OpenAI  # Import from Langfuse

client = OpenAI(
    base_url="https://inference.generativeai.<region>.oci.oraclecloud.com/openai/v1",
    api_key=os.getenv("OCI_GENAI_API_KEY"),
    project=os.getenv("OCI_GENAI_PROJECT_ID"),
)

After you instrument the client, send a Responses API request as usual. Langfuse automatically traces the request.

Example:

response = client.responses.create(
    model="openai.gpt-oss-120b",
    tools=[
        {
            "type": "mcp",
            "server_label": "dmcp",
            "server_url": "https://mcp.example.com/mcp",
            "require_approval": "never",
        },
    ],
    input="Explain why tracing and observability are important in distributed systems."
)

print(response.output_text)