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

> Map an eve agent's instructions, tools, connections, schedules, channels, and subagents to Guild agents, integrations, credentials, and triggers.

eve is Vercel's open-source, filesystem-first TypeScript framework for durable agents (Apache-2.0, in beta as of October 2026). An eve agent is a directory: instructions (`instructions.md` or an `instructions/` folder), `agent.ts`, and folders for tools, connections, schedules, channels, and subagents. Guild keeps that shape. Instructions become a prompt file, connections become Guild integrations, schedules and channels become triggers, and subagents become Guild agents you call as tools.

## Who this is for

Teams running eve agents on Vercel, or self-hosted, who want the agents in a shared workspace. That means a public or internal Hub to fork from, credentials the agent never sees, ALLOW/DENY credential policies, and one place to see every run.

## Concept map

| Guild | eve |
| - | - |
| `PROMPT.md` (Native), `AGENTS.md` (OpenClaw), or `systemPrompt` (TypeScript `llmAgent`) | `agent/instructions.md` or `agent/instructions/` |
| `guild.yaml` `models` fallback list, or account LLM settings | `defineAgent({ model })` |
| Integration operations registered with `pick(...)`, or pure functions in `logic.ts` | `agent/tools/*.ts` (`defineTool`) |
| [Guild integrations](https://docs.guild.ai/integrations/overview.md) | `agent/connections/*` (MCP or OpenAPI) |
| [Credentials](https://docs.guild.ai/platform/credentials.md) scoped to account, workspace, member, or agent | Connection auth, Vercel Connect OAuth |
| A Guild agent called with `guildAgentTool`, or `sub_agents` in `guild.yaml` | `agent/subagents/` |
| OpenClaw `skills/<name>/SKILL.md` | `agent/skills/` |
| Schedule [trigger](https://docs.guild.ai/platform/triggers.md) | `agent/schedules/*` |
| [API trigger](https://docs.guild.ai/platform/api-triggers.md) | HTTP channel |
| Event trigger on the matching integration | Slack, GitHub, Linear channels |
| A [credential policy](https://docs.guild.ai/platform/credential-policies.md) scoped to the agent (who can call it), plus a `ui_prompt` confirmation (sign-off on each call) | Tool `approval: always()` |
| OpenClaw's built-in shell, files, and git | Built-in `bash`, `read_file`, and `write_file` tools; `agent/sandbox.ts` |
| Guild Evaluations and `guild agent test` | `evals/**/*.eval.ts` |
| Guild session event log, Insights, and Spend Explorer | Agent Runs dashboard |
| `guild agent save --wait --publish` | `eve deploy` |

## Before you start

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

## Inventory

List these from the eve project before writing any Guild code. Record names only, never secret values.

* Every file in `agent/tools/` and what it calls (vendor SDK, `fetch`, database).
* Every file in `agent/connections/`, with its URL or OpenAPI spec and auth method.
* `agent/schedules/` cron expressions, `agent/channels/` entry points, and `agent/subagents/`.
* Tools with an `approval` policy.
* Whether the agent's instructions or tools rely on the built-in `bash`, `read_file`, or `write_file` tools. Every eve agent has a sandbox, and these tools are on unless `agent.ts` sets `defaultTools: false`.
* Environment variables the tools and connections read.

## Steps

**1. Pick the agent type and scaffold**

No shell or file work and text in/out: Native. Typed input or deterministic steps: TypeScript. Shell, file, or repository work: OpenClaw.

```bash theme={null}
guild agent init --name support-agent --agent-type GUILD_TYPESCRIPT --template LLM \
  --category <category> --owner <owner>
# or: --agent-type GUILD_NATIVE | OPENCLAW
```

`--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**

Copy `agent/instructions.md` into `PROMPT.md`, `AGENTS.md`, or the `systemPrompt` of an `llmAgent`. Update any tool names the prompt mentions. Guild tool names follow `{service}_{operation}`.

**3. Replace connections with integrations**

The Guild runtime has no general network egress, so each `fetch` or vendor SDK call becomes an integration operation.

```bash theme={null}
guild integration list
guild integration operation list <owner~integration> --json
```

If an API is missing, create it from its OpenAPI spec:

```bash theme={null}
guild integration create my-api --base-url https://api.example.com \
  --auth-scheme api-key --header-template "Authorization: Bearer {token}"
guild integration operation create my-api --openapi openapi.yaml
```

**4. Port tools and approvals**

```ts Guild: agent.ts theme={null}
"use agent";
import { agent, pick, userInterfaceTools, type Task } from "@guildai/agents-sdk";
import { StripeTools } from "@guildai-services/<owner>~stripe";
import { z } from "zod";

const inputSchema = z.object({ chargeId: z.string().max(100), amountCents: z.number().int().positive().max(1_000_000) });
const outputSchema = z.object({ status: z.enum(["refunded", "declined"]), refundId: z.string().optional() });
const tools = { ...pick(StripeTools, ["stripe_refunds_create"]), ...pick(userInterfaceTools, ["ui_prompt"]) };

async function run(input: z.infer<typeof inputSchema>, task: Task<typeof tools>) {
  const answer = await task.tools.ui_prompt({
    type: "text",
    text: `Refund ${input.amountCents / 100} on ${input.chargeId}? Reply "yes" to approve.`,
  });
  if (!/^\s*yes\b/i.test(answer.text)) return { status: "declined" as const };
  const refund = await task.tools.stripe_refunds_create({ charge: input.chargeId, amount: input.amountCents });
  return { status: "refunded" as const, refundId: refund.id };
}

export default agent({ description: "Refunds a charge after a human approves it.", inputSchema, outputSchema, tools, run });
```

```ts eve: agent/tools/refund.ts theme={null}
import { defineTool } from "eve/tools";
import { always } from "eve/tools/approval";
import { z } from "zod";

export default defineTool({
  description: "Refund a Stripe charge.",
  inputSchema: z.object({ chargeId: z.string(), amountCents: z.number().int().positive() }),
  approval: always(),
  async execute({ chargeId, amountCents }) {
    return stripe.refunds.create({ charge: chargeId, amount: amountCents });
  },
});
```

Tool names and parameters come from `guild integration operation list --json`; the ones above are illustrative.

The `ui_prompt` confirmation replaces eve's `approval: always()` as the sign-off on each call. To control which agents can call the operation at all, add a [credential policy](https://docs.guild.ai/platform/credential-policies.md) rule scoped to the agent and workspace. DENY wins.

**5. Turn subagents into Guild agents**

Each `agent/subagents/<name>/` becomes its own Guild agent. Call it with `guildAgentTool({ calls: "owner~agent", inputSchema, outputSchema })`, or list it under `sub_agents` in `guild.yaml`.

**6. Test**

```bash theme={null}
pnpm install && pnpm test
git add -A
guild agent test
```

The scaffold has no `test` script, so `pnpm test` passes without running anything. Add a `test` script to `package.json` before you rely on it, such as `"test": "tsc --build && node --test logic.test.mjs"`. If `pnpm install` fails with `ERR_PNPM_IGNORED_BUILDS`, newer pnpm is blocking esbuild's install script. Run `pnpm approve-builds`, approve esbuild, and install again.

`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'".

Send the same request the eve agent handled and compare the results.

**7. Publish and add triggers**

```bash theme={null}
guild agent save --message "Port from eve" --wait --publish
guild workspace agent add <owner~agent> --workspace <owner~workspace>
guild trigger create --workspace <owner~workspace> --type time --agent <owner~agent> \
  --frequency WEEKLY --time 08:00 --days-of-week MONDAY \
  --input '{"type":"text","text":"Summarize last week'"'"'s open issues."}'
```

> [!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 environment variable or connection token as a Guild [credential](https://docs.guild.ai/platform/credentials.md). Use member scope where eve used `defineDynamic` or user-owned Vercel Connect tokens, and workspace or agent scope for app-owned tokens. Then narrow access with [credential policies](https://docs.guild.ai/platform/credential-policies.md). New credentials start allow-all, and DENY rules win.

## What doesn't map 1:1

> [accordion] Per-tool approval policies
>
> eve's `approval: always()` and `once()` map to two Guild controls. To control which agents can call the operation at all, add a [credential policy](https://docs.guild.ai/platform/credential-policies.md) rule scoped to the agent and workspace that allows or denies that operation. DENY wins. To have a person sign off on each call, have the agent confirm with `ui_prompt` first. The run pauses until someone answers.

> [accordion] Self-hosting
>
> eve can run as a self-hosted Node service. Guild is a hosted platform, so self-hosted eve deployments move to Guild's runtime.

> [accordion] Cron schedules
>
> eve schedules take any standard 5-field cron expression and run in UTC. Guild supports the same expressions with `--frequency CRON --cron-expression "<expr>"`. Add `--cron-timezone`, such as `Europe/Athens`, and Guild converts the schedule to UTC.

> [accordion] Evals
>
> eve evals (`defineEval`, with Braintrust, JUnit, or Datadog reporters) do not run on Guild. Rebuild the important cases as Guild Evaluations or `guild agent test` sessions.

> [accordion] Channels without a Guild trigger
>
> eve channels such as Twilio (SMS and phone calls), iMessage through Linq or Photon, Discord, Microsoft Teams, or Telegram have no direct Guild trigger. Check `guild integration list` for the service first.

## Three ways to migrate

> [card] [guild-migrate skill](https://docs.guild.ai/migrations/guild-migrate-skill.md)
>
> Ask your coding agent: "Migrate the eve agent in `./agent` to Guild." It follows these steps 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.

A worked before/after example lives in `examples/migrations/vercel-eve/` in the guild-migrate repository.

## Related pages

> [card] [Agent types](https://docs.guild.ai/guide/agent-types.md)
>
> Native, TypeScript, Goose, OpenClaw, and LangGraph.

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