Migrate from Arcade to Guild

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, 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, 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 (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

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

Replace Arcade
Keep Arcade as the tool layer

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.

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.

Move the agent's instructions

PROMPT.md

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.

Map each Arcade toolkit to a Guild integration

guild integration operation list guildlabs~gmail-oauth --json

guild.yaml

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 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.

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:

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

Test

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’”.

Publish and add triggers

Arcade has no triggers. Guild agents can run on a schedule, on an event, or from an API call.

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"}'

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

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.

Scaffold the agent

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.

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.

guild integration create arcade-gateway --base-url https://api.arcade.dev --auth-scheme api-key \
  --header-template "Authorization: Bearer {token}"

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.

Declare the tools and test

Add the integration and the operations the agent calls to guild.yaml, then test:

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 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 on operations and resources.

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

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.

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.

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.

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.

Tool evals

arcade evals suites test tool selection and arguments. Rebuild them as Guild Evaluations with hasToolCall and toolCallContains checks.

Three ways to migrate

guild-migrate skill

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.

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 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.

Integrations

The catalog, and how to add an API that is not in it.

Credentials

Scopes, resolution order, and the credential proxy.

Overview

The Smith

The Factory

Platform

Agent SDK

Migrations

Migrate from Arcade 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

Integrations

Credentials

​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

Integrations

Credentials

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