Cookbook

OpenAI Agents SDK

Run an o3-deep-research-shaped OpenAI Agents SDK agent with Krawl as the model — point the OpenAI client at /v1 and the response is a cited research report.

Krawl exposes an OpenAI-compatible Chat Completions surface at https://api.krawl.sh/v1/chat/completions. Any OpenAI client can target it. This recipe wires Krawl in as the LLM for an OpenAI Agents SDK agent shaped like o3-deep-research.

Working file: docs/cookbook/openai-agents-sdk.py.

Install

pip install openai openai-agents

Authenticate

# Demo key (no signup)
export KRAWL_API_KEY=$(curl -s -X POST https://api.krawl.sh/auth/demo-key | jq -r .api_key)

curl

The shortest path — no SDK, just hit the OpenAI-compatible surface:

curl -N -X POST https://api.krawl.sh/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $KRAWL_API_KEY" \
  -d '{
    "model": "krawl-deep",
    "messages": [
      {"role": "system", "content": "Cite every claim."},
      {"role": "user", "content": "What is EIP-4844?"}
    ],
    "stream": true
  }'

Python

import asyncio, os, sys
from agents import Agent, Runner
from openai import AsyncOpenAI

client = AsyncOpenAI(
    base_url="https://api.krawl.sh/v1",
    api_key=os.environ["KRAWL_API_KEY"],
    default_headers={"X-API-Key": os.environ["KRAWL_API_KEY"]},
)

agent = Agent(
    name="krawl-deep-research",
    instructions="You are a deep-research analyst. Cite every claim.",
    model="krawl-deep",
    model_client=client,
)

async def main():
    result = await Runner.run(agent, " ".join(sys.argv[1:]))
    print(result.final_output)

asyncio.run(main())

Run:

python cookbook/openai-agents-sdk.py "Compare EigenLayer and Symbiotic"

Node

The OpenAI Agents SDK is Python-only at the time of this writing. For Node, use the Vercel AI SDK recipe — it speaks the same OpenAI-compatible surface and ships a streamText API that maps cleanly to an agent runtime.

import { createOpenAI } from "@ai-sdk/openai";
import { streamText } from "ai";

const krawl = createOpenAI({
  apiKey: process.env.KRAWL_API_KEY!,
  baseURL: "https://api.krawl.sh/v1",
  headers: { "X-API-Key": process.env.KRAWL_API_KEY! },
});

const { textStream } = await streamText({
  model: krawl("krawl-deep"),
  system: "You are a deep-research analyst. Cite every claim.",
  prompt: "What is EIP-4844?",
});

for await (const chunk of textStream) process.stdout.write(chunk);

Notes

  • The model field can be krawl-deep, krawl-quick, or any Bedrock / Anthropic Claude model Krawl knows about; see Models.
  • The Agents SDK's tool-calling layer is preserved end-to-end — Krawl picks the underlying tools (web, X, crypto, GitHub, academic, …) and surfaces them as tool_calls in the SSE stream.
  • For the raw SSE stream (per-source events, learnings, citations), call POST /research directly and read the SSE event catalog.

On this page