> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guild.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To act on a user's behalf in Guild, use the Guild REST API at https://api.guild.ai/v1.
> The OpenAPI spec is unauthenticated: https://docs.guild.ai/openapi.json (or openapi.yaml).
> Authenticate with an account API key, sent as HTTP Basic (key id as username, secret as password) or as `Authorization: Bearer <api_key_id>:<api_key_secret>`. See https://docs.guild.ai/api-reference/introduction#authentication.
> To run one agent on demand without account-wide access, use an API trigger instead: https://docs.guild.ai/platform/api-triggers.
> To act on Guild from an MCP client, connect to https://api.guild.ai/mcp (OAuth) or run `guild mcp` locally. Setup: https://docs.guild.ai/api-reference/mcp.
> To search these docs from an MCP client, connect to https://docs.guild.ai/mcp. The full page index is https://docs.guild.ai/llms.txt.

# Migrate from the OpenAI Agents API to Guild

> Move OpenAI Agents API agents to Guild Native or OpenClaw agents, and map MCP tools, vaults, automations, and subagents 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.

> [!NOTE]
>
> 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](https://docs.guild.ai/guide/native-agents.md), which runs without a container |
| Environment `openai_hosted` (Bash, apply-patch, `/workspace`) | An [OpenClaw agent](https://docs.guild.ai/guide/openclaw-agents.md), which has shell, file, and git tools built in |
| Session and turns (`/v1/agents/sessions`) | A Guild [session](https://docs.guild.ai/platform/sessions.md) 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](https://docs.guild.ai/services/create-an-integration.md) created from the server's URL in the web app, with only the allowed operations registered |
| Vaults (`static_bearer`, `mcp_oauth`, `environment_variable`) | [Credentials](https://docs.guild.ai/platform/credentials.md) 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](https://docs.guild.ai/platform/skills.md) |
| Automations (`type: "periodic"`, `expression`, `timezone`) | A [schedule trigger](https://docs.guild.ai/platform/schedule-triggers.md) with `--frequency CRON` and `--cron-timezone` |
| App code that calls `sessions.create` | An [API trigger](https://docs.guild.ai/platform/api-triggers.md), 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](https://docs.guild.ai/platform/credential-policies.md) 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

```bash theme={null}
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:

```bash theme={null}
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

> [tab] No environment → Native
>
> Use this path for agents that run with `environment: {"type": "none"}`: instructions plus MCP or function tools, text in and out.
>
> **1. Scaffold a Native agent**
>
> ```bash theme={null}
> 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`.
>
> **2. Move the instructions and tools**
>
> ```yaml Guild: guild.yaml theme={null}
> models:
>   - provider: openai
>   - provider: anthropic
> integrations:
>   - name: guildai~github
>     version: ^1.0.0
>     tools: [github_issues_list_for_repo, github_issues_add_labels]
> ```
>
> ```python OpenAI Agents API theme={null}
> 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](https://docs.guild.ai/services/create-an-integration.md).
>
> A `function` tool your app answered becomes an integration operation, or moves to a TypeScript agent when it needs real logic.
>
> **3. Test**
>
> ```bash theme={null}
> 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`.

> [tab] Hosted sandbox → OpenClaw
>
> 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`.
>
> **1. Scaffold an OpenClaw agent**
>
> ```bash theme={null}
> 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`.
>
> **2. 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`.
>
> **3. Test**
>
> ```bash theme={null}
> 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:

```bash theme={null}
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](https://docs.guild.ai/platform/api-triggers.md) or [`guild workspace chat --once`](https://docs.guild.ai/cli/commands/workspace) instead.

> [!NOTE]
>
> 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](https://docs.guild.ai/migrations/overview.md#publish-from-github-actions) GitHub Action instead of `guild agent save --publish`. The Action needs an account API key with the `agents:write` scope:

```bash theme={null}
guild api-key create --owner <owner> --name "Publish migrated agent" --scopes agents:write
```

## Credentials and policies

Recreate each vault credential as a Guild [credential](https://docs.guild.ai/platform/credentials.md) 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](https://docs.guild.ai/platform/credential-policies.md) 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

> [accordion] 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.

> [accordion] 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.

> [accordion] Approvals and auto review
>
> `review: "auto_review"` has a model review actions before they run. Guild has no automatic reviewer. Use [credential policies](https://docs.guild.ai/platform/credential-policies.md) to limit which operations the agent can call, and a `ui_prompt` confirmation where a person should sign off.

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

> [accordion] 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.

> [accordion] 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

> [card] [guild-migrate skill](https://docs.guild.ai/migrations/guild-migrate-skill.md)
>
> 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`.

> [card] [Publish Agent to Guild Action](https://docs.guild.ai/migrations/overview.md#publish-from-github-actions)
>
> Commit the port to your repository, then publish it from GitHub Actions with an account API key.

> [card] [Migration agent](https://app.guild.ai/organizations/guildai/agents/guildai~migrate-to-guild)
>
> Point Migrate to Guild at your repository; it opens a draft pull request. The guild-migrate skill ships in the same package.

## Related pages

> [card] [OpenClaw agents](https://docs.guild.ai/guide/openclaw-agents.md)
>
> `AGENTS.md`, skills, and the coding toolchain.

> [card] [guild.yaml](https://docs.guild.ai/guide/guild-yaml.md)
>
> Models, integrations, sub-agents, and builtins.

Migrating a team? [Talk to us](https://www.guild.ai/talk-to-sales?utm_source=docs\&utm_medium=referral\&utm_campaign=migrations).