Migrate from the OpenAI Agents API to Guild

The OpenAI Agents API runs OpenAI’s Codex agent harness as a hosted service, in public beta since September 2026. An agent is a model, instructions, and tools. A session is a durable instance of it that runs in no environment, an OpenAI-hosted sandbox, or a self-hosted executor. Vaults hold credentials, automations run sessions on a schedule, and webhooks report session events. The Agents API has no config file. An agent is defined by API calls, under client.beta.agents, in the application that uses it. Agents without a sandbox move to Guild Native, and agents that work in the sandbox move to OpenClaw.

This guide covers the hosted Agents API. The open-source OpenAI Agents SDK (openai-agents or @openai/agents) runs the agent loop in your own application; port that code to a Guild TypeScript or Native agent.

Who this is for

Teams running agents on the OpenAI Agents API who want models from more than one provider, ready-made integrations, and agents that start from Slack mentions or GitHub events instead of only their own API calls.

Concept map

OpenAI Agents API	Guild
Saved agent (`POST /v1/agents`)	A Guild agent, versioned with each `guild agent save`
`instructions`	`PROMPT.md` in a Native agent, or `AGENTS.md` in an OpenClaw agent
`model` (OpenAI models only)	The `models` fallback list in `guild.yaml`, which can include other providers
Environment `none`	A Native agent, which runs without a container
Environment `openai_hosted` (Bash, apply-patch, `/workspace`)	An OpenClaw agent, which has shell, file, and git tools built in
Session and turns (`/v1/agents/sessions`)	A Guild session and its event log
`function` tools your app executes	An integration operation, or a function in `logic.ts` in a TypeScript agent
`mcp` tools with `allowed_tools`	The catalog integration for the same service, or a custom MCP integration created from the server’s URL in the web app, with only the allowed operations registered
Vaults (`static_bearer`, `mcp_oauth`, `environment_variable`)	Credentials on the integration; the credential proxy keeps them out of the agent
`text.format` JSON schema	`outputSchema` (zod) on a TypeScript agent
`multi_agent` subagents	A separate Guild agent, called with `guildAgentTool` or listed under `sub_agents` in `guild.yaml`
Skills in `capability_directories`, `.codex-plugin` plugins	`skills/<name>/SKILL.md` in an OpenClaw agent (same format), or a Guild skill
Automations (`type: "periodic"`, `expression`, `timezone`)	A schedule trigger with `--frequency CRON` and `--cron-timezone`
App code that calls `sessions.create`	An API trigger, or `guild workspace chat --once`
`review: "auto_review"` and computer-use approvals	No automatic reviewer. A `ui_prompt` confirmation before each call, plus a credential policy that limits which agents can call it
Tracing (Logs > Agents, OTLP export)	The session event log, Insights, and Spend Explorer
Org and project spend limits	Spend budgets per workspace, agent, or user

Before you start

guild auth login
guild workspace select

Inventory

An agent’s definition is spread across your code: the saved agent, overrides on each session (a session’s tools array replaces the saved one), the environment, vault_ids, and review. If the agent was created in a script that isn’t in the repository, export it first:

curl https://api.openai.com/v1/agents/$AGENT_ID \
  -H "Authorization: Bearer $OPENAI_API_KEY" -H "OpenAI-Beta: agents=v1"
curl https://api.openai.com/v1/agents/sessions/$SESSION_ID \
  -H "Authorization: Bearer $OPENAI_API_KEY" -H "OpenAI-Beta: agents=v1"

The saved agent holds the model, instructions, tools, text.format, and multi_agent. A typical session holds the environment, vault_ids, and review. Then list, by name only, never secret values:

The instructions, the model, and any structured output schema.
Every function tool and the code in your app that answers it.
Every mcp tool: its server URL, allowed_tools, and the vault credential it uses.
The environment type, and whether the agent relies on Bash, file patches, or files under /workspace.
Skills in capability_directories, and plugins.
Automations (cron expression and timezone) and webhook handlers.
Vault credentials and environment variables, by name only.

Steps

No environment → Native
Hosted sandbox → OpenClaw

Use this path for agents that run with environment: {"type": "none"}: instructions plus MCP or function tools, text in and out.

Scaffold a Native agent

guild agent init --name issue-triage --agent-type GUILD_NATIVE \
  --category <category> --owner <owner>

--category and --owner stop the CLI from prompting, which a script or coding agent can’t answer. List categories with guild agent categories.

Move the instructions and tools

models:
  - provider: openai
  - provider: anthropic
integrations:
  - name: guildai~github
    version: ^1.0.0
    tools: [github_issues_list_for_repo, github_issues_add_labels]

agent = client.beta.agents.create(
    model="gpt-6-astra",
    instructions="Triage new GitHub issues and label each one.",
    tools=[{"type": "mcp", "server_label": "github",
            "transport": {"type": "http", "server_url": GITHUB_MCP_URL},
            "allowed_tools": ["search_issues", "add_labels"],
            "connection_origin": "service"}],
)

Copy instructions into PROMPT.md. Each mcp tool becomes the catalog integration for the same service, with only the operations the agent calls. Check the real names with guild integration operation list <owner~integration> --json. For an MCP server with no catalog integration, create one from the server’s URL in the web app by choosing the MCP protocol in Create an integration.A function tool your app answered becomes an integration operation, or moves to a TypeScript agent when it needs real logic.

Test

git add -A
guild agent test

guild agent test collects files by walking your local directory and honoring .gitignore, the same way guild agent save does, so new files such as logic.ts are uploaded even without git add.

Use this path for agents that run in an openai_hosted or self_hosted environment and rely on Bash, file patches, or files under /workspace.

Scaffold an OpenClaw agent

guild agent init --name repo-fixer --agent-type OPENCLAW \
  --category <category> --owner <owner>

--category and --owner stop the CLI from prompting, which a script or coding agent can’t answer. List categories with guild agent categories.

Move the instructions and skills

Copy instructions into AGENTS.md. Copy each skill directory from capability_directories into skills/<name>/; skills keep the same SKILL.md format. Declare integrations for the services the agent calls in guild.yaml.An OpenClaw agent’s workspace is rebuilt from its committed files on every task, so files it writes don’t carry over. Return results in the reply or through an integration, where the source agent wrote to /workspace/outputs.

Test

git add -A
guild agent test

guild agent test collects files by walking your local directory and honoring .gitignore, the same way guild agent save does, so new files such as logic.ts are uploaded even without git add.

Then publish, and recreate each automation as a schedule trigger. Guild converts a timezone schedule to UTC:

guild agent save --message "Port from the OpenAI Agents API" --wait --publish
guild workspace agent add <owner~agent> --workspace <owner~workspace>
guild trigger create --workspace <owner~workspace> --type time --agent <owner~agent> \
  --frequency CRON --cron-expression "0 9 * * 1-5" --cron-timezone America/New_York \
  --input '{"type":"text","text":"Triage today'"'"'s issues."}'

App code that called sessions.create can use an API trigger or guild workspace chat --once instead.

The first guild agent save --wait --publish after guild agent init fails with “No saved state… use —force” because of the .gitignore the scaffold writes. Add --force to that first save for now.

You can also publish with the Publish Agent to Guild GitHub Action instead of guild agent save --publish. The Action needs an account API key with the agents:write scope:

guild api-key create --owner <owner> --name "Publish migrated agent" --scopes agents:write

Credentials and policies

Recreate each vault credential as a Guild credential on the matching integration. Use member scope for MCP servers that each person connected with their own account, and workspace or agent scope for service accounts. Like vaults, the credential proxy keeps secret values out of the agent. Guild splits a tool approval into two controls:

Who can call it. Add a credential policy rule scoped to the agent and workspace that allows or denies the operation. DENY wins over ALLOW.
Sign-off on each call. Add the ui_prompt built-in and have the agent confirm with the user before it calls the tool. The run pauses until someone answers.

What doesn’t map 1:1

Self-hosted executors

codex exec-server runs the sandbox on your own compute. Guild runs agents in its own containers, so self-hosted environments move to Guild’s runtime.

Steering a running turn

A message sent to a busy Agents API session changes the turn in progress. On Guild, a follow-up message starts the next turn.

Approvals and auto review

review: "auto_review" has a model review actions before they run. Guild has no automatic reviewer. Use credential policies to limit which operations the agent can call, and a ui_prompt confirmation where a person should sign off.

Computer use

Guild has no computer-use tool. For browser work, use a browser integration from the catalog in an OpenClaw agent.

Webhooks and one-off automations

Guild has no outbound session webhooks. Have the agent post its result through an integration, such as Slack or GitHub. A one-off type: "once" automation, or an agent that schedules its own follow-ups with the automations tool, has no equivalent.

Local MCP servers

Guild connects to remote MCP servers by URL. An MCP server started with command and args needs a hosted HTTP endpoint first. Otherwise, move its tools to an integration built from the service’s OpenAPI spec.

Three ways to migrate

guild-migrate skill

Ask your coding agent: “Migrate the Agents API agent in this repository to Guild.” It finds the client.beta.agents calls and writes MIGRATION.md.

Publish Agent to Guild Action

Commit the port to your repository, then publish it from GitHub Actions with an account API key.

Migration agent

Point Migrate to Guild at your repository; it opens a draft pull request. The guild-migrate skill ships in the same package.

OpenClaw agents

AGENTS.md, skills, and the coding toolchain.

guild.yaml

Models, integrations, sub-agents, and builtins.

Migrating a team? Talk to us.

Overview

The Smith

The Factory

Platform

Agent SDK

Migrations

Migrate from the OpenAI Agents API to Guild

Who this is for

Concept map

Before you start

Inventory

Steps

Credentials and policies

What doesn’t map 1:1

Three ways to migrate

guild-migrate skill

Publish Agent to Guild Action

Migration agent

OpenClaw agents

guild.yaml

​Who this is for

​Concept map

​Before you start

​Inventory

​Steps

​Credentials and policies

​What doesn’t map 1:1

​Three ways to migrate

guild-migrate skill

Publish Agent to Guild Action

Migration agent

​Related pages

OpenClaw agents

guild.yaml

Who this is for

Concept map

Before you start

Inventory

Steps

Credentials and policies

What doesn’t map 1:1

Three ways to migrate

Related pages