Run OpenAI Agents API code against Claude, Gemini, GPT and the rest of the models Ragwalla serves. Use OpenAI's SDK for hosted agents and sessions, or point OpenAI's Agents SDK at Ragwalla to run your own loop on any model.

Run OpenAI Agents API code against Claude, Gemini, GPT and the rest of the models Ragwalla serves.

What is the OpenAI Agents API on Ragwalla?

Ragwalla serves OpenAI's Agents API at https://api.ragwalla.com/v1/agents. You keep using OpenAI's official SDK (client.beta.agents) and change two things: the base URL and the API key. The agent's model can then be any model Ragwalla serves, not only OpenAI's.

There are two ways to use it, and they answer different needs:

You want Use Where the agent loop runs
Agents, sessions and turns that Ragwalla stores and runs for you The Agents API (client.beta.agents) On Ragwalla
An agent loop in your own process, written with OpenAI's Agents SDK The Agents SDK (openai-agents, @openai/agents) pointed at Ragwalla's model gateway In your code

Both take the same model ids, and both bill to your Ragwalla account. You do not need an OpenAI, Anthropic or Google key.


Model ids

Pass a Ragwalla model id wherever OpenAI's code takes model.

Provider Example id Notes
OpenAI gpt-6-luna Bare ids with no slash are OpenAI's.
Anthropic claude-sonnet-5-5, claude-opus-5-5, claude-haiku-5-5 Anthropic's own spelling. anthropic/claude-sonnet-4.5 (OpenRouter's spelling) also works.
Google google/gemini-3.8-flash Vendor-qualified, as Cloudflare's model catalogue lists it.
Others xai/grok-4, @cf/zai-org/glm-5.2 Any text model in Cloudflare AI Gateway's catalogue.

To see every model your key can use, list them:

curl https://api.ragwalla.com/v1/models \
  -H "Authorization: Bearer $RAGWALLA_API_KEY"

Each entry carries a ragwalla.provider field that names who serves it.


Quick start: the Agents API

You need OpenAI's Python SDK at version 3.41.0 or later, which includes client.beta.agents, and a Ragwalla API key. The key's project is where your agents are created.

pip install "openai>=3.41.0"
export RAGWALLA_API_KEY="your Ragwalla API key"

1. Point the client at Ragwalla

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.ragwalla.com/v1",
    api_key=os.environ["RAGWALLA_API_KEY"],
)

The SDK marks every beta.agents call with the OpenAI-Beta: agents=v1 header. That header is what routes the request to the Agents API. Without it, /v1/agents is Ragwalla's native agents API.

2. Create an agent on Claude

agent = client.beta.agents.create(
    name="Support triage",
    model="claude-sonnet-5-5",
    instructions="You triage support requests. Answer in two sentences or fewer.",
)
print(agent.id)

To run the same agent on Gemini, change only the model:

agent = client.beta.agents.create(
    name="Support triage",
    model="google/gemini-3.8-flash",
    instructions="You triage support requests. Answer in two sentences or fewer.",
)

3. Open a session

A session is a conversation with an agent. On Ragwalla, a session always runs a saved agent, its environment is of type none, and it opens with its first message.

session = client.beta.agents.sessions.create(
    agent_id=agent.id,
    environment={"type": "none"},
    input="A customer says their invoice was charged twice. What do I do first?",
)
print(session.id, session.status)

The call returns once the turn has started. Wait for the session's status to return to idle, or stream the turn as shown next.

4. Stream a turn

with client.beta.agents.sessions.stream(
    session.id,
    input="Draft the reply to the customer.",
) as stream:
    for event in stream:
        if event.type == "agent.session.turn.output_text.delta":
            print(event.delta, end="", flush=True)
    result = stream.get_final_result()

print()
print(result.turn.status)  # "completed"

A streamed turn sends agent.session.turn.created, then agent.session.turn.output_text.delta as the model writes, then the turn's end event, and finally agent.session.idle.

To stream the first turn as well, pass stream=True to sessions.create. The stream then starts with agent.session.created.

5. Read the conversation back

for item in client.beta.agents.sessions.items.list(session.id):
    print(item.type, getattr(item, "role", None))

for turn in client.beta.agents.sessions.turns.list(session.id, order="asc"):
    print(turn.id, turn.status, turn.usage)

Switching models

The model is a setting of the agent, so you can change it without touching your code.

For every future session, update the agent:

client.beta.agents.update(agent.id, model="claude-opus-5-5")

For one session only, override it when you open the session. The saved agent is unchanged.

session = client.beta.agents.sessions.create(
    agent_id=agent.id,
    agent={"model": "google/gemini-3.8-flash"},
    environment={"type": "none"},
    input="Summarize this ticket in one line: ...",
)

A model change applies from the next turn. A turn that is already running keeps the model it started with.


Function tools your code runs

Give an agent function tools and the session's client runs them. When the model calls one, the turn waits (requires_action) until your code sends the result back. With the SDK's stream helper, pass a handler per function and the SDK does the round trip for you.

import json

agent = client.beta.agents.create(
    name="Order desk",
    model="claude-sonnet-5-5",
    instructions="Use lookup_order to answer questions about orders.",
    tools=[
        {
            "type": "function",
            "name": "lookup_order",
            "description": "Look up an order by its id.",
            "parameters": {
                "type": "object",
                "properties": {"order_id": {"type": "string"}},
                "required": ["order_id"],
                "additionalProperties": False,
            },
        }
    ],
)

def lookup_order(arguments: dict) -> str:
    # Call your own systems here.
    return json.dumps({"order_id": arguments["order_id"], "status": "shipped"})

session = client.beta.agents.sessions.create(
    agent_id=agent.id, environment={"type": "none"}, input="Hello"
)

with client.beta.agents.sessions.stream(
    session.id,
    input="Where is order A-1042?",
    tool_handlers={"lookup_order": lookup_order},
) as stream:
    for event in stream:
        pass
    result = stream.get_final_result()

The session's items then include the function_call and its function_call_output.

Tools that Ragwalla runs for the agent (knowledge bases, MCP servers, APIs, built-in tools) are granted with Ragwalla's native tool routes, not with tools. A session reports them, and refuses a tools list that changes or leaves one out.


Structured output

Ask for JSON that matches a schema with text.format, on the agent or on a session:

agent = client.beta.agents.create(
    name="Extractor",
    model="google/gemini-3.8-flash",
    instructions="Extract the country and its capital.",
    text={
        "format": {
            "type": "json_schema",
            "name": "capital",
            "schema": {
                "type": "object",
                "properties": {"country": {"type": "string"}, "city": {"type": "string"}},
                "required": ["country", "city"],
                "additionalProperties": False,
            },
        }
    },
)

reasoning.effort is supported the same way, for models that reason.


Cancelling, resuming and webhooks

  • Cancel a turn. Send a cancel event. The turn ends cancelled.

    client.beta.agents.sessions.events.create(
        session.id, events=[{"type": "agent.session.input.cancel"}]
    )
    
  • Resume a dropped stream. GET /v1/agents/sessions/{session_id}/events takes the standard Last-Event-ID header. Every event has a stable id, and Ragwalla replays what you missed for 15 minutes after a turn ends. An idle stream carries a : ping comment every 15 seconds, so proxies do not close it.

  • Webhooks. Sessions send OpenAI's agent.session.created, agent.session.in_progress, agent.session.action_required and agent.session.idle events, in OpenAI's envelope, signed with the Standard Webhooks headers that OpenAI's SDK verifies.


Using OpenAI's Agents SDK with any model

If you would rather run the agent loop in your own process, use OpenAI's Agents SDK and point its client at Ragwalla. The SDK calls Ragwalla's /v1/responses (or /v1/chat/completions), and Ragwalla routes each call to the model you name.

Python

pip install openai-agents
import asyncio
import os

from openai import AsyncOpenAI
from agents import Agent, Runner, function_tool, set_default_openai_client, set_tracing_disabled

client = AsyncOpenAI(
    base_url="https://api.ragwalla.com/v1",
    api_key=os.environ["RAGWALLA_API_KEY"],
)
set_default_openai_client(client, use_for_tracing=False)
# The SDK uploads traces to OpenAI by default. Turn that off, or give it an OpenAI key.
set_tracing_disabled(True)


@function_tool
def get_weather(city: str) -> str:
    """The current weather in a city."""
    return f"It is sunny in {city}."


claude = Agent(
    name="Claude assistant",
    model="claude-sonnet-5-5",
    instructions="Answer briefly. Use tools when they help.",
    tools=[get_weather],
)

gemini = Agent(
    name="Gemini assistant",
    model="google/gemini-3.8-flash",
    instructions="Answer briefly. Use tools when they help.",
    tools=[get_weather],
)


async def main() -> None:
    for agent in (claude, gemini):
        result = await Runner.run(agent, "What's the weather in Lisbon?")
        print(agent.model, "->", result.final_output)


asyncio.run(main())

Handoffs work across providers too. An agent on Claude can hand off to one on Gemini, since each agent names its own model and every call goes through the same client.

TypeScript

npm install @openai/agents openai
import OpenAI from 'openai';
import { Agent, run, setDefaultOpenAIClient, setTracingDisabled } from '@openai/agents';

setDefaultOpenAIClient(
  new OpenAI({
    baseURL: 'https://api.ragwalla.com/v1',
    apiKey: process.env.RAGWALLA_API_KEY,
  }),
);
setTracingDisabled(true);

const agent = new Agent({
  name: 'Claude assistant',
  model: 'claude-sonnet-5-5',
  instructions: 'Answer in one sentence.',
});

const result = await run(agent, 'What is retrieval-augmented generation?');
console.log(result.finalOutput);

Web search

WebSearchTool works on every model. Ragwalla runs each search itself and cites the pages the answer uses as url_citation annotations, so you need no search key of your own.

from agents import Agent, Runner, WebSearchTool

researcher = Agent(
    name="Researcher",
    model="google/gemini-3.8-flash",
    instructions="Answer with current facts. Cite your sources.",
    tools=[WebSearchTool(search_context_size="low")],
)

result = await Runner.run(researcher, "What changed in the latest Cloudflare Workers pricing?")
print(result.final_output)
Setting Effect
search_context_size Pages returned per search: low 5, medium 10 (the default), high 20.
max_tool_calls Caps the searches in one response, shared with FileSearchTool. The default is 8.
include=["web_search_call.action.sources"] Lists the pages each search found on its web_search_call item.
user_location, filters Not yet. Refused with a 400.

Each search is billed as one tool step.

What the gateway serves

Feature Supported Notes
Function tools Yes Returned to the SDK as function_call items, for any model.
Streaming Yes In the Responses event grammar, for any model.
FileSearchTool Yes Searches your Ragwalla vector stores, by their ids.
WebSearchTool Yes Searches the web for any model, with url_citation annotations.
Other hosted tools (code interpreter, MCP, image generation) Not yet Refused with a 400 rather than silently dropped. Until they are served, run them as function tools in your own code.
previous_response_id, conversation, store: true, background No Gateway calls are stateless. Send the whole conversation as input, or use the Agents API above to keep one.

A Responses call to a model that OpenAI does not serve is translated for you and marked ragwalla.translated in the response.


What differs from OpenAI

Ragwalla implements the Agents API as OpenAI specifies it (version 2.3.0), with these differences:

Area On Ragwalla
Models Any model Ragwalla serves, not only OpenAI's.
Environments Sessions use environment: {"type": "none"}. Ragwalla agents run their tools themselves. /v1/agents/environments returns 501.
Vaults Not supported. Agents use the credentials configured on their tools. vault_ids is refused.
Sessions Run a saved agent: pass agent_id. A session opens with its first input.
Session overrides agent.model, agent.reasoning, agent.text and agent.tools may be overridden per session. agent.instructions and agent.multi_agent may not; update the agent instead.
Events Submit one message event per request. Each starts one turn.
Settings service_tier is auto, text.verbosity is medium, and reasoning summaries are not returned.
Tools defer_loading is not supported: the model is offered every function.

Everything else (agents, sessions, turns, items, subagents, traces, artifacts and automations) follows OpenAI's spec, and every response is checked against it in Ragwalla's tests.


API reference summary

Method Path Description
POST /v1/agents Create an agent
GET /v1/agents List agents
GET / POST / DELETE /v1/agents/{agent_id} Retrieve, update or delete an agent
POST /v1/agents/sessions Open a session with its first input
GET /v1/agents/sessions List sessions
GET / POST / DELETE /v1/agents/sessions/{session_id} Retrieve, update or delete a session
POST /v1/agents/sessions/{session_id}/events Send a message, a tool result or a cancel
GET /v1/agents/sessions/{session_id}/events Stream a session's events
GET /v1/agents/sessions/{session_id}/items List a session's items
GET /v1/agents/sessions/{session_id}/turns List turns, and their items
GET /v1/agents/sessions/{session_id}/subagents List subagents, their turns and items
GET /v1/agents/sessions/{session_id}/traces List traces
GET /v1/agents/sessions/{session_id}/artifacts List artifacts
POST / GET /v1/agents/automations Create or list automations

Every request to these paths carries OpenAI-Beta: agents=v1. OpenAI's SDK adds it for you.