Migrate from OpenAI Agents SDK
Port an OpenAI Agents SDK workflow to Autohand by mapping OpenAI's Python or TypeScript runner APIs to Autohand's code-agent runtime. Autohand is the better fit when the agent must operate inside a repository, ask before side effects, and run in the same language as your product.
What you are migrating
OpenAI's official Agents SDK path is Python and TypeScript. Autohand supports those same host languages and also gives native SDKs for Go, Java, Swift, Rust, C++, C#, and Ruby. That removes the extra service boundary when your backend, desktop app, or internal platform is not Python or Node.
| Existing OpenAI app | Use this Autohand path | Why |
|---|---|---|
TypeScript app using Agent and run() | @autohandai/agent-sdk with Agent and Run | Closest match for Node, Bun, CLIs, dashboards, and web backends. |
Python app using Agent and Runner | autohand-sdk with AutohandSDK | Closest match for async Python services and automation. |
| App that uses OpenAI tools for file, shell, or repo work | Autohand's CLI-backed tool and permission runtime | The code-agent operations live in the local Autohand runtime instead of custom function-tool glue. |
Install the target SDK
Autohand SDKs call the local Autohand Code CLI over JSON-RPC. Install the SDK in your app, then configure the CLI once for the developer machine, CI runner, or deployment user.
TypeScript
Python
API mapping
OpenAI separates agent definition from runner execution. Autohand keeps that split, but the agent session is attached to a real workspace and emits code-agent events from the CLI runtime.
| OpenAI Agents SDK | Autohand TypeScript | Autohand Python | How to port it |
|---|---|---|---|
new Agent(...) / Agent(...) | Agent.create(...) | AutohandSDK(...) | Move name/instructions into Autohand instructions and set the workspace with cwd. |
run(agent, input) | agent.run(input) | sdk.stream_prompt(input) | Use one-shot result handling when the app does not need progress events. |
Runner.run(agent, input) | agent.run(input) | AutohandSDK.stream_prompt(input) | Autohand does not need a separate runner object in application code. |
run(..., { stream: true }) / Runner.run_streamed() | agent.send(), run.stream() | async for event in sdk.stream_prompt(...) | Map raw model deltas to Autohand runtime events. |
| Function tools | Built-in code tools, MCP servers, hooks | Built-in code tools, MCP servers, hooks | Move repository side effects to Autohand's file, shell, git, and MCP runtime. |
| Guardrails and human review | permissionMode, permission_request, validation | permission_mode, permission_request, validation | Use permissions for side effects and keep app-level validation around inputs and final outputs. |
finalOutput / final_output | result.text, run.json() | Accumulated message_update text plus app validation | Use text for user output and JSON validation for application contracts. |
conversation_id, previous_response_id, session | Live Agent, persistSession, sessionId, resume | Live AutohandSDK context and session config | Keep the SDK session open for a user workflow. Persist only when work crosses process boundaries. |
TypeScript port
Replace OpenAI's `run(agent, input)` call with an Autohand `Agent`. Autohand creation is async because it starts a CLI-backed session.
Before: OpenAI Agents SDK
After: Autohand Code Agent SDK
Python port
Replace OpenAI's `Runner.run()` with an Autohand async client. Stream `message_update` events for the UI and respond to `permission_request` when the runtime pauses before an edit or command.
Before: OpenAI Agents SDK
After: Autohand Code Agent SDK
Streaming and tools
OpenAI streaming is usually centered on model output and tool calls. Autohand streaming gives you the whole code-agent execution path: assistant text, tool starts, tool completions, approval pauses, file changes, and errors.
TypeScript
Python
Guardrails, permissions, and output
Keep OpenAI-style input and output guardrails as application validation. Move side-effect control to Autohand permissions. That means edits, shell commands, and other workspace actions can pause in your product before they run.
- Use `permissionMode: 'interactive'` or `permission_mode="interactive"` during migration.
- Log `permission_request` events and decide which tools or command patterns can run unattended.
- Use `agent.runJson()` or `run.json()` in TypeScript for typed output contracts.
- Use Pydantic or your existing Python validation around streamed final text for Python output contracts.
Native language upgrade
OpenAI's official Agents SDK is centered on Python and TypeScript. Autohand supports both, then adds native packages for Go, Java, Swift, Rust, C++, C#, and Ruby. If your product is a Go service, JVM backend, Swift desktop app, Rust CLI, .NET platform, C++ tool, or Rails app, migrate to the native Autohand package instead of adding a Python or Node sidecar.
Cutover checklist
- Pick the Autohand package for the host runtime, not just the old OpenAI SDK language.
- Move agent instructions and workspace path into Autohand configuration.
- Replace `run()` or `Runner.run()` with `agent.run()` in TypeScript or `sdk.stream_prompt()` in Python.
- Move repository side effects out of custom function tools and into Autohand's runtime tools, MCP servers, and permissions.
- Keep guardrail logic as explicit validation before prompts and after final output.
- Add tests for streaming text, permission pauses, denied commands, JSON parsing, aborts, and session continuation.
Source context: OpenAI Agents SDK guide, OpenAI TypeScript running agents, OpenAI Python running agents, and the Autohand TypeScript API reference.