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

> Move agents from Vercel eve, LangChain and LangGraph, Runlayer, or Arcade to Guild with a skill, a GitHub Action, or an agent that opens a pull request.

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.

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

> [card] [Vercel eve](https://docs.guild.ai/migrations/vercel-eve.md)
>
> Map the `agent/` directory (tools, connections, schedules, channels, subagents, sandbox) to Guild agents, integrations, and triggers.

> [card] [LangChain, LangGraph, LangSmith](https://docs.guild.ai/migrations/langchain.md)
>
> Run Python LangGraph graphs as Guild LangGraph agents, port `createAgent` to TypeScript, and move Fleet agents to Native.

> [card] [Runlayer](https://docs.guild.ai/migrations/runlayer.md)
>
> Rebuild Runlayer Agents as Native or OpenClaw agents with Guild integrations, credential policies, and triggers.

> [card] [Arcade](https://docs.guild.ai/migrations/arcade.md)
>
> 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](https://docs.guild.ai/guide/native-agents.md) | No container, ready right after init |
| Typed input/output or deterministic steps | [TypeScript](https://docs.guild.ai/guide/coded-agents.md) | `agent.ts` with `@guildai/agents-sdk` |
| A Python LangGraph v1 graph | [LangGraph](https://docs.guild.ai/guide/langgraph-agents.md) | `langgraph.json` + `graph.py`, models and tools through Guild |
| Shell, files, git, or a repository | [OpenClaw](https://docs.guild.ai/guide/openclaw-agents.md) | `AGENTS.md` + `skills/`, built-in coding toolchain |
| A portable recipe with parameters | [Goose](https://docs.guild.ai/guide/goose-agents.md) | `recipe.yaml` with a response schema |

See [Agent types](https://docs.guild.ai/guide/agent-types.md) for the full comparison.

## Three ways to migrate

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

> [card] [The Publish Agent to Guild Action](#publish-from-github-actions)
>
> Once the port is in your repository, publish it from GitHub Actions with an account API key. Guild never needs access to the repository.

> [card] [The migration agent](https://app.guild.ai/organizations/guildai/agents/guildai~migrate-to-guild)
>
> 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

```bash theme={null}
npm install -g @guildai/cli
guild auth login
guild workspace list
guild workspace select
```

> [!NOTE]
>
> Never copy secret values from the source platform into the new agent. Recreate each one as a Guild [credential](https://docs.guild.ai/platform/credentials.md). 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](https://github.com/marketplace/actions/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](https://docs.guild.ai/cli/github-actions.md) covers automatic releases, multiple agents, and troubleshooting.

### Prepare your account

1. Create an [account API key](https://docs.guild.ai/platform/api-keys.md) in the Guild account that will own the agent. Give it **Agents: Read & write** (`agents:write`).
2. 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.
3. Choose a target in `owner~name` form, such as `myorg~hello`. The owner must match the key's Guild account.

> [!WARNING]
>
> 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:

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

```yaml theme={null}
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`](https://docs.guild.ai/cli/github-actions#add-a-release-workflow) do before the first run, then follow [Release and verify](https://docs.guild.ai/cli/github-actions.md#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.

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

## Related pages

> [card] [CLI commands](https://docs.guild.ai/cli/introduction.md)
>
> Every `guild` command used in these guides.

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

> [card] [Triggers](https://docs.guild.ai/platform/triggers.md)
>
> Event, schedule, and API triggers.

> [card] [Credential policies](https://docs.guild.ai/platform/credential-policies.md)
>
> ALLOW/DENY rules by operation, resource, agent, and workspace.