From kitaru
Migrate existing OpenAI Agents SDK code to Kitaru's OpenAI Agents adapter. Use when code mentions agents.Agent, Runner.run, Runner.run_sync, KitaruRunner, OpenAIRunRequest, OpenAIRunResult, wait_for_approval, build_resume_request, function_tool, RunConfig, handoffs, context, approval/resume flows, or checkpoint_strategy. Helps classify direct, approximate, and absent mappings, choose runner_call vs calls boundaries, preserve OpenAI Agents SDK ownership of the agent turn, and produce a MIGRATION_REPORT.md with replay, context, approval, tool, and side-effect risks called out.
How this skill is triggered — by the user, by Claude, or both
Slash command
/kitaru:kitaru-openai-agents-migrationThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Use this skill to inspect existing OpenAI Agents SDK code and move the safe
Use this skill to inspect existing OpenAI Agents SDK code and move the safe
execution boundary to Kitaru's KitaruRunner, OpenAIRunRequest, and
OpenAIRunResult surfaces.
The output should be conservative:
direct,
approximate, or absent.MIGRATION_REPORT.md section or file that names behavior changes and
review risks.Do not promise that Kitaru can see or replay OpenAI/provider internals that stay inside the OpenAI Agents SDK.
Think of the OpenAI Agents SDK as the driver of the agent turn. It decides how handoffs, guardrails, model calls, hosted tools, and approvals work.
Kitaru changes the doorway you use to enter that turn:
from agents import Agent, Runner
from kitaru.adapters.openai_agents import KitaruRunner, OpenAIRunRequest
agent = Agent(name="researcher", model="gpt-5-nano")
# Before: enter through the raw OpenAI SDK runner.
raw_result = Runner.run_sync(agent, "Research durable workflows")
# After: enter through Kitaru's runner doorway.
runner = KitaruRunner(agent, checkpoint_strategy="runner_call")
result = runner.run_sync(OpenAIRunRequest.start("Research durable workflows"))
Concrete story: the agent starts, calls a model, maybe calls tools, maybe pauses for approval, and then returns a final answer. OpenAI still runs that story. Kitaru records either one durable checkpoint around the whole runner call or supported model/local-tool calls that the adapter can safely see.
Use it when the user asks to:
agents.Agent workflows to Kitaru.Runner.run(...) or Runner.run_sync(...) with KitaruRunner.checkpoint_strategy="runner_call" versus "calls".context=..., RunConfig, hosted tools, function tools, API
keys, or raw nested runner calls are safe under Kitaru replay.Do not use it to:
wait() calls inside checkpoints.Classify each source pattern before editing:
direct: Kitaru has a close adapter surface for the same behavior. Example:
Runner.run_sync(agent, input) becomes
runner.run_sync(OpenAIRunRequest.start(input)).approximate: The code can move, but semantics, observability, cache keys,
or replay behavior differ. Example: RunConfig(...) becomes a
run_config_factory, which recreates config per Kitaru run.absent: There is no safe automatic migration. Add a # TODO(migration)
comment, do not pretend it is solved, and explain the redesign needed in the
report.Agent(...) construction,
Runner.run / Runner.run_sync, RunConfig, context=..., tools,
approvals, handoffs, guardrails, nested runner calls, and API-key handling.references/concept-map.md and
references/gaps-and-flags.md. Count direct, approximate, high-risk, and
blocked items.checkpoint_strategy="runner_call" or "calls". Prefer runner_call when
the surrounding flow needs a clean .wait() result.agents.Agent. Replace raw runner
entrypoints with KitaruRunner plus OpenAIRunRequest. Add status handling
for OpenAIRunResult.MIGRATION_REPORT.md. Include the pattern inventory, chosen
boundary, classifications, flags, behavior differences, and verification
plan.Look for:
from agents import Agent, Runner, agents.Agent, or Runner.run*.agents.Runner.run(...) calls inside tools, guardrails, or helper
agents.RunConfig(...), tracing configuration, hooks, guardrails, and handoffs.@function_tool, FunctionTool, hosted tools, web search/file search/code
interpreter tools, or custom tool wrappers.context=..., RunContextWrapper, context objects, serializers, and cache
identity needs.OpenAICapturePolicy should save inputs, outputs, run state,
interruption payloads, response items, and usage.result.status, interrupted, resume state, and
manual approval decisions.final_output use without checking status.Runner.run_sync(...) inside async code or an active event loop.agents.Agent(...) as the OpenAI-owned agent definition.KitaruRunner(agent, checkpoint_strategy="runner_call") when the flow
needs one durable result and ergonomic .wait() behavior.checkpoint_strategy="calls" when per-model/per-local-tool visibility is
more important than a single terminal flow result.calls mode inside an existing Kitaru checkpoint.wait_for_approval(...) at flow scope, not checkpoint scope.context= as OpenAI Agents SDK runtime context, not Kitaru metadata.context_cache_identity= for production context objects so replay does
not mix tenants, users, threads, or tool settings.Minimal durable sync replacement:
from agents import Agent
from kitaru import flow
from kitaru.adapters.openai_agents import KitaruRunner, OpenAIRunRequest
agent = Agent(name="support_agent", model="gpt-5-nano")
runner = KitaruRunner(agent, checkpoint_strategy="runner_call")
@flow
def support_flow(message: str) -> str:
result = runner.run_sync(OpenAIRunRequest.start(message))
if result.status != "completed":
raise RuntimeError(f"Expected completed run, got {result.status!r}")
return str(result.final_output)
print(support_flow.run("Where is order ORD-1007?").wait())
Outside an explicit Kitaru flow, this is only adapter API wiring; it does not establish a durable Kitaru checkpoint.
For full examples, load references/code-patterns.md.
When a pattern is unsafe or unsupported:
# TODO(migration): ... comment near the code if you are
producing code.LOW, MEDIUM, HIGH, or BLOCKER.Use references/gaps-and-flags.md for severity definitions and required
actions.
Every non-trivial migration must include or draft MIGRATION_REPORT.md with:
Use references/report-template.md when a full report is needed.
Avoid these:
agents.Agent internals instead of changing the runner doorway.Runner.run_sync(...) from inside an active event loop.result.final_output without checking result.status when approval
interruptions are possible.checkpoint_strategy="calls" inside a Kitaru @checkpoint.wait_for_approval(...) or kitaru.wait(...) inside a checkpoint.Load only the reference file needed for the current task:
references/concept-map.md — source-to-target mapping table and
classification guidance.references/code-patterns.md — import-complete migration examples.references/gaps-and-flags.md — severity definitions and must-flag patterns.references/report-template.md — OpenAI-specific migration report template.Kitaru source references:
kitaru/docs/content/docs/adapters/openai-agents.mdxkitaru/src/kitaru/adapters/openai_agents/__init__.pykitaru/examples/integrations/openai_agents_agent/openai_agents_adapter.py
and kitaru/examples/end_to_end/openai_research_bot/research_bot.pynpx claudepluginhub zenml-io/kitaru-skills --plugin kitaruGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.