> ## 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 Arcade to Guild

> Move the agent behind your Arcade tools to Guild: map toolkits to integrations and requires_auth to credentials, or keep Arcade as the tool layer.

Arcade is an actions runtime for AI agents. It provides per-user OAuth for tools, a catalog of more than 100 integrations, MCP Gateways, tool-level policy hooks, and `arcade evals` for tool selection. Tools are written in Python with the open-source `arcade-mcp` framework. Arcade does not run agents: the agent itself lives in a framework such as LangChain, OpenAI Agents, the Vercel AI SDK, or Mastra, or in your own loop, and calls Arcade through `arcadepy`, `@arcadeai/arcadejs`, or an MCP Gateway.

A move to Guild therefore has two halves. The agent becomes a Guild agent with a runtime, triggers, sessions, and a Hub listing. The tools become Guild integrations, or stay on Arcade behind a custom integration.

## Who this is for

Teams whose agent code calls Arcade tools and who want the agent itself hosted, triggered, versioned, and shared, with tool credentials brokered by the same platform.

## Concept map

| Guild | Arcade |
| - | - |
| Catalog [integrations](https://docs.guild.ai/integrations/overview.md), tools named `{service}_{operation}` | Prebuilt toolkits (Gmail, Slack, GitHub, Linear, Notion, Google Calendar) |
| Custom integration from an OpenAPI spec or MCP server (`guild integration create`) | Custom `MCPApp` server and `@app.tool` |
| Integration [credential](https://docs.guild.ai/platform/credentials.md), member-scoped for per-person access | `requires_auth=<Provider>()` |
| Credentials or workspace variables | `requires_secrets` |
| The Guild member or agent whose credential resolves for the session | `user_id` on each call |
| Connect the credential in Guild once | `client.tools.authorize` and `wait_for_completion` |
| `guild.yaml` `integrations` (Native, OpenClaw, LangGraph) or `pick(...)` in `agent.ts` | `client.tools.execute` inside an agent loop |
| Integrations declared on the agent, or a custom integration that fronts the gateway | MCP Gateway |
| [Credential policies](https://docs.guild.ai/platform/credential-policies.md) (ALLOW/DENY) | Contextual Access hooks |
| Guild Evaluations and `guild agent test` | `arcade evals` |
| Session event log and the org audit log | Tool execution records and the admin audit log |

## Before you start

```bash theme={null}
guild auth login
guild workspace select
guild integration list
```

## Inventory

Collect from the repository, by name only:

* The agent framework and its entry point (such as LangChain, OpenAI Agents, Vercel AI SDK, Mastra, Google ADK, CrewAI, or a custom loop).
* Every Arcade tool name the code calls, such as `Gmail.ListEmails`. Arcade renamed tools across most toolkits in October 2026, so use the names in the code.
* Every custom `MCPApp` tool, its `requires_auth` provider and scopes, and its `requires_secrets` names.
* How `user_id` is chosen: a teammate, or an end user of your own product.
* Any MCP Gateway URLs (`api.arcade.dev/mcp/<slug>`) and the auth mode they use (Arcade Auth, User Source, or Arcade Headers).
* Contextual Access hooks and what they allow, deny, modify, or redact.
* `eval_*.py` suites.

## Steps

> [tab] Replace Arcade
>
> **1. Pick the agent type and scaffold**
>
> A tool-calling loop with text in and out becomes a Native agent. Typed input or deterministic steps become TypeScript.
>
> ```bash theme={null}
> guild agent init --name inbox-digest --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 agent's instructions**
>
> ```markdown PROMPT.md theme={null}
> You summarize the user's latest emails. List the 10 most recent messages, group them by sender,
> and flag anything that needs a reply today.
> ```
>
> **3. Map each Arcade toolkit to a Guild integration**
>
> ```bash theme={null}
> guild integration operation list guildlabs~gmail-oauth --json
> ```
>
> ```yaml guild.yaml theme={null}
> models:
>   - provider: anthropic
> integrations:
>   - name: guildlabs~gmail-oauth
>     version: ^1.0.1
>     tools: [gmail_oauth_users_messages_list, gmail_oauth_users_threads_get]
> ```
>
> Connect the Gmail [credential](https://docs.guild.ai/platform/credentials.md) in the Guild web app once. This replaces Arcade's authorize-and-wait flow: Guild injects the credential into every call from then on, so the agent needs no connect step.
>
> **4. Port custom MCPApp tools**
>
> A custom tool usually wraps an API that already has a Guild integration. For example, a `requires_auth=GitHub()` tool that comments on issues becomes `github_issues_create_comment` from `guildai~github`. For an API with no integration, create one from its OpenAPI spec:
>
> ```bash theme={null}
> guild integration create <name> --base-url https://api.example.com --auth-scheme oauth
> guild integration operation create <name> --openapi openapi.yaml
> guild integration operation list <owner~name> --json
> ```
>
> **5. Test**
>
> ```bash theme={null}
> git add -A
> guild agent test
> ```
>
> `guild agent test` uploads only the files git tracks, so `git add -A` stages new files such as `logic.ts` first. Without it, the cloud build fails with "Cannot find module './logic.ts'".
>
> **6. Publish and add triggers**
>
> Arcade has no triggers. Guild agents can run on a schedule, on an event, or from an API call.
>
> ```bash theme={null}
> guild agent save --message "Port from Arcade" --wait --publish
> guild workspace agent add <owner~agent> --workspace <owner~workspace>
> guild trigger create --workspace <owner~workspace> --type time --agent <owner~agent> \
>   --frequency DAILY --time 08:00 --input '{"type":"text","text":"Summarize my inbox"}'
> ```
>
> > [!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
> ```

> [tab] Keep Arcade as the tool layer
>
> Move only the agent to Guild and keep calling Arcade tools through the MCP Gateway. This fits agents that depend on Arcade-only toolkits, or on per-user OAuth for your own product's customers.
>
> **1. Scaffold the agent**
>
> ```bash theme={null}
> guild agent init --name inbox-digest --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. Create a custom integration for the gateway**
>
> Register the Arcade MCP Gateway (`https://api.arcade.dev/mcp/<slug>`) as a custom integration, with the Arcade API key stored as a Guild credential.
>
> ```bash theme={null}
> guild integration create arcade-gateway --base-url https://api.arcade.dev --auth-scheme api-key \
>   --header-template "Authorization: Bearer {token}"
> ```
>
> > [!WARNING]
> >
> > Verify this path before relying on it. The gateway is a Streamable HTTP MCP endpoint at `/mcp/<slug>`, not a REST API, and it is not yet confirmed that a Guild custom integration can front a remote MCP server. The gateway must use the **Arcade Headers** auth mode, which takes `Authorization: Bearer <API key>` and an `Arcade-User-ID` header per end user. Arcade's other auth modes (Arcade Auth and User Source) need a browser OAuth flow that a custom integration can't complete.
>
> **3. Declare the tools and test**
>
> Add the integration and the operations the agent calls to `guild.yaml`, then test:
>
> ```bash theme={null}
> git add -A
> guild agent test
> ```
>
> `guild agent test` uploads only the files git tracks, so `git add -A` stages new files such as `logic.ts` first. Without it, the cloud build fails with "Cannot find module './logic.ts'".

## Credentials and policies

* `requires_auth` providers become integration credentials. Use member-scoped credentials when each teammate connects their own account, and [identity mapping](https://docs.guild.ai/platform/identity-mapping.md) so Slack- or GitHub-started runs act as the right person.
* `requires_secrets` values become credentials or workspace variables. Never copy secret values; recreate them in Guild.
* Arcade Contextual Access rules that allow or deny become [credential policies](https://docs.guild.ai/platform/credential-policies.md) on operations and resources.

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] Per-end-user OAuth for your own customers
>
> Arcade authorizes any `user_id` your app passes, so a SaaS product can connect thousands of its own customers' accounts. Guild credentials belong to Guild members, workspaces, or agents. For that pattern, keep Arcade as the tool layer.

> [accordion] Modify and redact hooks
>
> Arcade pre- and post-execution hooks can rewrite or redact tool inputs and outputs. Guild credential policies only allow or deny, so move that logic into the agent.

> [accordion] Hosting MCP servers
>
> `arcade deploy` hosts your own MCP servers. Guild hosts agents and brokers integrations; publish the API behind the server as a custom integration instead.

> [accordion] Self-hosted and air-gapped deployments
>
> Arcade can run in your own cloud: from a cloud marketplace, self-hosted with Helm, or in your VPC or air-gapped on its Enterprise plan. Guild is hosted only.

> [accordion] Tool evals
>
> `arcade evals` suites test tool selection and arguments. Rebuild them as Guild Evaluations with `hasToolCall` and `toolCallContains` checks.

## Three ways to migrate

> [card] [guild-migrate skill](https://docs.guild.ai/migrations/guild-migrate-skill.md)
>
> Ask your coding agent: "Migrate this Arcade agent to Guild." It maps each Arcade tool to an integration and ports the agent with its framework's reference.

> [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 the repository and it opens a draft pull request with the Guild agent and `MIGRATION.md`. The guild-migrate skill ships in the same package.

A worked example (an Arcade `MCPApp` server with a GitHub tool and an agent script using `arcadepy`, then the Guild agent) lives in `examples/migrations/arcade/` in the guild-migrate repository.

## Related pages

> [card] [Integrations](https://docs.guild.ai/integrations/overview.md)
>
> The catalog, and how to add an API that is not in it.

> [card] [Credentials](https://docs.guild.ai/platform/credentials.md)
>
> Scopes, resolution order, and the credential proxy.