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/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}/eventstakes the standardLast-Event-IDheader. Every event has a stable id, and Ragwalla replays what you missed for 15 minutes after a turn ends. An idle stream carries a: pingcomment every 15 seconds, so proxies do not close it.Webhooks. Sessions send OpenAI's
agent.session.created,agent.session.in_progress,agent.session.action_requiredandagent.session.idleevents, 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.