Migrate to Guild

Every migration to Guild follows the same four steps, whatever the source platform: inventory what the agent uses, map each piece to a Guild primitive, scaffold the Guild agent with the CLI, and prove it runs with guild agent test. The guides below give the concept map and CLI commands for each platform. They also list what does not map 1:1, so nothing gets lost.

source repo -> detect platform -> inventory (tools, models, triggers, secrets by name)
            -> pick Guild agent type -> guild agent init -> port -> guild agent test
            -> MIGRATION.md -> (you decide) guild agent save --publish

Pick your platform

Vercel eve

Map the agent/ directory (tools, connections, schedules, channels, subagents, sandbox) to Guild agents, integrations, and triggers.

LangChain, LangGraph, LangSmith

Run Python LangGraph graphs as Guild LangGraph agents, port createAgent to TypeScript, and move Fleet agents to Native.

Runlayer

Rebuild Runlayer Agents as Native or OpenClaw agents with Guild integrations, credential policies, and triggers.

Arcade

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

Choose the Guild agent type

You have	Guild agent type	Why
Instructions plus tools, text in and out	Native	No container, ready right after init
Typed input/output or deterministic steps	TypeScript	`agent.ts` with `@guildai/agents-sdk`
A Python LangGraph v1 graph	LangGraph	`langgraph.json` + `graph.py`, models and tools through Guild
Shell, files, git, or a repository	OpenClaw	`AGENTS.md` + `skills/`, built-in coding toolchain
A portable recipe with parameters	Goose	`recipe.yaml` with a response schema

See Agent types for the full comparison.

Three ways to migrate

The guild-migrate skill

Load it into Claude Code, Codex, or Cursor and ask it to migrate a directory. It ships in the Migrate to Guild agent package. It detects the platform, scaffolds with the Guild CLI, ports, tests, writes MIGRATION.md, and stops before publishing.

The Publish Agent to Guild Action

Once the port is in your repository, publish it from GitHub Actions with an account API key. Guild never needs access to the repository.

The migration agent

Migrate to Guild, a TypeScript agent on Guild. Point it at a repository and it opens a draft pull request with the ported agent and its MIGRATION.md. The package includes the guild-migrate skill.

Before you start

npm install -g @guildai/cli
guild auth login
guild workspace list
guild workspace select

Never copy secret values from the source platform into the new agent. Recreate each one as a Guild credential. The proxy injects auth server-side, so the agent never sees the secret.

Publish from GitHub Actions

Once the migrated agent is in your repository and guild agent test passes, publish it with the Publish Agent to Guild Action. The Action uploads the agent directory, validates it, and publishes a version. Your repository can be private: the workflow sends the files to Guild, so Guild never needs access to it. Publish from GitHub Actions covers automatic releases, multiple agents, and troubleshooting.

Prepare your account

Create an account API key in the Guild account that will own the agent. Give it Agents: Read & write (agents:write).
In your GitHub repository, open Settings > Secrets and variables > Actions. Add the full <api_key_id>:<api_key_secret> value as a repository secret named GUILD_API_KEY. Don’t commit the key or paste it into a coding-agent conversation.
Choose a target in owner~name form, such as myorg~hello. The owner must match the key’s Guild account.

The key can write every agent in its account, not just this one. Give it only to trusted release workflows. Never expose it to untrusted pull-request code.

You need permission to add workflows and configure Actions secrets in the repository. Your GitHub organization must also allow the Action to run. If these controls are restricted, ask your repository owner. You don’t need to install a GitHub App or authorize Guild to read the repository. To create the key from the CLI instead:

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

Add a release workflow

Save this as .github/workflows/publish-agent.yml:

name: Publish agent
on:
  workflow_dispatch:
    inputs:
      version:
        description: New agent version
        required: true
        default: '1.0.0'
        type: string

permissions:
  contents: read

concurrency:
  group: guild-publish-myorg-hello
  cancel-in-progress: false

jobs:
  publish:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
        with:
          persist-credentials: false
      - name: Publish to Guild
        id: publish
        uses: guildaidev/publish-agent-action@v1.0.0
        with:
          path: agents/hello
          agent: myorg~hello
          version: ${{ inputs.version }}
          create-if-missing: 'true'
          agent-type: GOOSE
          overwrite: 'true'
        env:
          GUILD_API_KEY: ${{ secrets.GUILD_API_KEY }}

Then adjust it for your repository:

Replace myorg~hello with your target, and agents/hello with your agent directory.
If your default branch isn’t main, change the branch condition.
Merge the workflow onto your default branch. Run workflow appears only after the merge.

For a migrated agent, also:

Set path to the folder guild agent init created, and agent-type to the type you scaffolded: GUILD_TYPESCRIPT, GUILD_NATIVE, LANGGRAPH, or OPENCLAW.
Read what create-if-missing and overwrite do before the first run, then follow Release and verify.

Set up with a coding agent

Copy this prompt into Claude Code, Codex, or another coding agent that has access to your repository. The agent prepares a workflow for you to review. It never asks for your key or publishes without your confirmation.

Help me publish agents from this repository to Guild using the official Action:
https://github.com/marketplace/actions/publish-agent-to-guild
Read the setup guide: https://docs.guild.ai/cli/github-actions

1. Inspect the repository and propose agent directories, types, and dependencies.
   Check Guild's supported package format. Report incompatibilities; do not
   silently remove unsupported recipe fields or change agent behavior.
2. Ask me to confirm the Guild owner~name target for each directory, whether
   missing targets may be created privately, and whether repository source may
   replace Guild editor changes. Ask whether releases should be manual or on merge.
3. Add a workflow using guildaidev/publish-agent-action@v1.0.0 with contents: read,
   checkout with persist-credentials: false, and the confirmed directory mapping.
   Use per-target concurrency with cancel-in-progress: false. Keep publishing off
   pull_request and pull_request_target; pass GUILD_API_KEY only to the publish step.
4. Tell me how to create an account key with Agents: Read & write and store it as
   the GUILD_API_KEY Actions secret. Never ask me to paste it here, read it back,
   print it, or commit it. Explain any extra dependency-read permissions needed.
5. Use an explicit version per target: 1.0.0 for a new agent, otherwise higher
   than the latest published version. Do not assume the Action reads VERSION files.
   For automatic releases, keep versions in source and explain where to bump them.
6. Validate the YAML and workflow, then show me the diff for approval. Do not
   merge, trigger a release, change visibility, or create a workspace without asking.
   After I authorize a test release, verify the resulting agent/version and report
   any validation errors. Publishing success does not prove runtime behavior.

CLI commands

Every guild command used in these guides.

Integrations

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

Triggers

Event, schedule, and API triggers.

Credential policies

ALLOW/DENY rules by operation, resource, agent, and workspace.

Overview

The Smith

The Factory

Platform

Agent SDK

Migrations

Migrate to Guild

Pick your platform

Vercel eve

LangChain, LangGraph, LangSmith

Runlayer

Arcade

Choose the Guild agent type

Three ways to migrate

The guild-migrate skill

The Publish Agent to Guild Action

The migration agent

Before you start

Publish from GitHub Actions

Prepare your account

Add a release workflow

Set up with a coding agent

CLI commands

Integrations

Triggers

Credential policies

​Pick your platform

Vercel eve

LangChain, LangGraph, LangSmith

Runlayer

Arcade

​Choose the Guild agent type

​Three ways to migrate

The guild-migrate skill

The Publish Agent to Guild Action

The migration agent

​Before you start

​Publish from GitHub Actions

​Prepare your account

​Add a release workflow

​Set up with a coding agent

​Related pages

CLI commands

Integrations

Triggers

Credential policies

Pick your platform

Choose the Guild agent type

Three ways to migrate

Before you start

Publish from GitHub Actions

Prepare your account

Add a release workflow

Set up with a coding agent

Related pages