Create the guild-migrate skill

# Vercel eve → Guild

eve is Vercel's open-source (Apache-2.0), filesystem-first TypeScript framework for durable agents, in beta as of 2026-10-27. An eve agent is the `agent/` directory (or `agents/<name>/agent/` in a multi-agent workspace): every file is a slot the framework discovers.

Sources: https://vercel.com/docs/eve, https://eve.dev/docs/reference/agent-files, https://eve.dev/docs/tools.md, https://eve.dev/docs/connections, https://eve.dev/docs/schedules.md

## Detection signals

- `agent/instructions.md` (or `instructions.ts`, or an `instructions/` directory) and `agent/agent.ts` (`defineAgent`).
- `agent/tools/*.ts` importing `defineTool` from `eve/tools`.
- `agent/connections/*.ts` importing from `eve/connections`.
- `agent/schedules/*.ts|*.md`, `agent/channels/`, `agent/subagents/` (directories or single files), `agent/skills/`, `agent/sandbox.ts` or `agent/sandbox/`, `agent/memory.ts` or `agent/memory/`, `agent/hooks/`.
- `evals/**/*.eval.ts`; `eve` in `package.json` dependencies or scripts (`eve dev`, `eve deploy`).

## Choosing the Guild type

Every eve agent has a sandbox, and the built-in `bash`, `read_file`, and `write_file` tools are on unless `agent.ts` sets `defaultTools: false`. Decide by whether the agent's instructions or tools actually rely on them:

- Tools plus instructions, no shell or file work → **Native** if text in/out is enough, otherwise **TypeScript** (`llmAgent` for prompt-driven, `agent` for code-driven).
- Relies on `bash`, `read_file`, or `write_file`, customizes `agent/sandbox.ts` or `agent/sandbox/`, or works on a repository → **OpenClaw**.
- Mostly deterministic `run` code with typed I/O → **TypeScript** `agent`.

## Concept map

| eve | Guild |
|---|---|
| `agent/instructions.md` | `PROMPT.md` (Native), `AGENTS.md` (OpenClaw), or `systemPrompt` (TypeScript `llmAgent`) |
| `agent/agent.ts` `defineAgent({ model })` | `guild.yaml` `models` fallback list, or account LLM settings for TypeScript |
| `agent/tools/<name>.ts` `defineTool` | Guild integration operation via `pick(...)`, or a pure function in `logic.ts` called from `run` |
| `agent/connections/*` `defineMcpClientConnection` / `defineOpenAPIConnection` | Guild integration (`guild integration create` from the OpenAPI spec or MCP server) |
| Connection `auth: { getToken }`, Vercel Connect OAuth | Guild credential (account / workspace / member / agent scope) behind the credential proxy |
| `agent/subagents/<name>/` | Separate Guild agent called with `guildAgentTool({ calls: "owner~agent" })`, or `sub_agents` in `guild.yaml` |
| `agent/skills/` | OpenClaw `skills/<name>/SKILL.md`, or Guild Hub skills |
| `agent/schedules/*` `defineSchedule({ cron })` | `guild trigger create --type time` |
| `agent/channels/` HTTP | `guild trigger create --type api` |
| `agent/channels/` Slack, GitHub, Linear | `guild trigger create --type webhook --integration <slack|github|linear> --event …` |
| Tool `approval: always()` / `once()` | Credential policy scoped to the agent (who can call it) plus a `ui_prompt` confirmation (sign-off on each call) |
| Built-in `bash`, `read_file`, `write_file`; `agent/sandbox.ts` or `agent/sandbox/` | OpenClaw built-in shell, files, and git |
| `agent/memory/` | `task.save` / `task.restore` (TypeScript), or `MEMORY.md` (OpenClaw, read-only per task) |
| `evals/**/*.eval.ts` | Guild Evaluations (`/platform/evaluations`) and `guild agent test` cases |
| Agent Runs dashboard, OpenTelemetry | Guild session event log, Insights, Spend Explorer |
| `eve deploy` | `guild agent save --wait --publish` + `guild workspace agent add` |

## Before / after: a tool with approval

eve (`agent/tools/refund.ts`):

```ts
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 });
  },
});
```

Guild TypeScript (`agent.ts`, abbreviated). The refund goes through a Guild integration, and the sign-off becomes an explicit `ui_prompt` confirmation that pauses the run. A credential policy scoped to this agent controls which agents can call the refund operation at all:

```ts
"use agent";
import { agent, pick, userInterfaceTools, type Task } from "@guildai/agents-sdk";
import { StripeTools } from "@guildai-services/<owner>~stripe"; // from `guild integration list`
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 });
```

Check the real tool name and parameter shape with `guild integration operation list <owner~stripe> --json`; the names above are illustrative.

## Before / after: a schedule

eve (`agent/schedules/digest.ts`):

```ts
import { defineSchedule } from "eve/schedules";
export default defineSchedule({ cron: "0 8 * * 1", content: "Summarize last week's open Linear issues." });
```

Guild:

```bash
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 Linear issues."}'
```

## Pitfalls

- eve tool files often call vendor SDKs or `fetch` directly. Guild runtime has no network egress: replace each call with an integration operation.
- eve tool names are file names; Guild tool names come from the integration (`{service}_{operation}`). Update prompts that mention tool names.
- `defineDynamic` per-tenant connections → member-scoped credentials plus identity mapping, not code.
- eve schedules run in UTC on Vercel Cron. Guild `CRON` triggers take the same expression plus an optional `--cron-timezone`, and Guild converts the schedule to UTC.

## Gaps

- Tool approvals become a credential policy scoped to the agent and workspace (who can call it) plus a `ui_prompt` confirmation before the call (sign-off on each call; the run pauses until someone answers).
- eve can self-host as a Node service; Guild is hosted only.
- eve evals (`defineEval`, with Braintrust, JUnit, or Datadog reporters) do not run on Guild; rebuild key cases as Guild Evaluations.
- 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` first.

# LangChain, LangGraph, LangSmith → Guild

LangChain and LangGraph are open-source agent libraries (Python and JS). LangChain v1 provides `createAgent` / `create_agent`; LangGraph is the graph and durable-state runtime. LangSmith is the commercial platform: tracing, evals, Deployment (formerly LangGraph Platform), and Fleet (the no-code agent builder, formerly Agent Builder). Facts as of 2026-10-27.

Sources: https://docs.langchain.com/oss/javascript/langchain/agents, https://docs.langchain.com/langsmith/cli, https://docs.langchain.com/langsmith/fleet, https://docs.langchain.com/langsmith/deployment, https://docs.guild.ai/guide/langgraph-agents.md

## Detection signals

- `langgraph.json` with `graphs`, `dependencies`, `env`.
- Python: `from langchain.agents import create_agent`, `from langgraph.graph import StateGraph`; MCP through `langchain_mcp_adapters` (archived) or `from langchain.mcp import MCPAdapter` (`langchain[mcp]`); `langgraph` / `langchain` / `langsmith` in `pyproject.toml` or `requirements.txt`.
- JS: `createAgent` from `langchain`; `@langchain/langgraph`, `@langchain/mcp-adapters` in `package.json`.
- `LANGSMITH_API_KEY` / `LANGSMITH_TRACING` (or the legacy `LANGCHAIN_API_KEY` / `LANGCHAIN_TRACING_V2`) in `.env.example`.
- Fleet: a no-code agent description, its connections list, and its triggers (Slack, Teams, Gmail, Outlook, schedule, webhook).

## Three paths

### Path A: Python LangGraph → Guild LangGraph agent (closest port)

Guild runs LangGraph v1 graphs directly. Keep the graph; swap the model and tools.

Constraints: Python 3.13; only `langchain`, `langchain-core`, `langchain-openai`, `langgraph`, and `guildai_langchain` are installed; no other pip packages; no general network access; `langgraph.json` targets must be relative `.py` paths (`./graph.py:graph`); convert module paths such as `pkg.mod:graph` to `./pkg/mod.py:graph`.

Before (`graph.py`):

```python
from langchain.agents import create_agent
from langchain_anthropic import ChatAnthropic
from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient({"github": {"url": "https://mcp.example.com/github", "transport": "streamable_http"}})

async def graph():
    tools = await client.get_tools()
    return create_agent(ChatAnthropic(model="claude-sonnet-5-5"), tools, system_prompt="Triage new GitHub issues.")
```

After (`graph.py`), with tools declared in `guild.yaml`:

```python
from guildai_langchain import guild_model, guild_tools
from langchain.agents import create_agent

async def graph():
    return create_agent(guild_model(), await guild_tools(), system_prompt="Triage new GitHub issues.")
```

```json
{ "dependencies": ["."], "graphs": { "agent": "./graph.py:graph" } }
```

```yaml
# guild.yaml
integrations:
  - name: guildai~github
    version: ^1.0.0
    tools: [github_issues_list_for_repo, github_issues_update]
```

Steps: `guild agent init --name <name> --agent-type LANGGRAPH --category <category> --owner <owner>`, replace the scaffold `graph.py`, move tool access into `guild.yaml`, remove provider packages (`langchain-anthropic`, `langchain-mcp-adapters` or `langchain[mcp]`) and their API keys, then `git add -A` and `guild agent test`.

### Path B: JS `createAgent` → Guild TypeScript

```ts
// before
import { createAgent, humanInTheLoopMiddleware } from "langchain";
const agent = createAgent({
  model: "anthropic:claude-sonnet-5-5",
  tools: [searchDocs, createTicket],
  systemPrompt: "Answer support questions; open a ticket when you cannot.",
  middleware: [humanInTheLoopMiddleware({ interruptOn: { create_ticket: true } })],
});
```

```ts
// after (agent.ts)
"use agent";
import { llmAgent, pick, userInterfaceTools } from "@guildai/agents-sdk";
import { ZendeskTools } from "@guildai-services/<owner>~zendesk"; // from `guild integration list`

export default llmAgent({
  description: "Answers support questions and opens a ticket, after confirmation, when it cannot.",
  tools: { ...pick(ZendeskTools, ["zendesk_search", "zendesk_tickets_create"]), ...pick(userInterfaceTools, ["ui_prompt"]) },
  systemPrompt: "Answer support questions. Before creating a ticket, ask the user to confirm with ui_prompt.",
  mode: "multi-turn",
});
```

Use `agent({ ..., run })` instead of `llmAgent` when the graph has deterministic branches; each LangGraph node becomes a function, edges become ordinary control flow, and parallel branches become an inline `task.gather([...])`.

### Path C: LangSmith Fleet → Guild Native

Fleet agents are instructions plus connections plus triggers. Port them to `PROMPT.md` + `guild.yaml` (`guild agent init --name <name> --agent-type GUILD_NATIVE --category <category> --owner <owner>`), then recreate triggers with `guild trigger create`. For each tool set to "Ask", add the `ui` built-in with `ui_prompt` and tell the agent to confirm before calling it. Fleet "Claws" (fixed credentials) → workspace- or agent-scoped credentials; Fleet "Assistants" and per-user connections (act as the invoker) → member-scoped credentials with identity mapping.

## Concept map

| LangChain / LangGraph / LangSmith | Guild |
|---|---|
| `create_agent` / `createAgent` | LangGraph agent (Python) or `llmAgent` (TypeScript) |
| `StateGraph` nodes and edges | LangGraph agent unchanged, or TypeScript `agent` `run` control flow |
| Model string (`anthropic:…`) | `guild_model()` (Python) / `guild.yaml` `models` / account LLM settings |
| Tools (`@tool`, MCP adapters) | Guild integrations declared in `guild.yaml` or `pick(...)` |
| `humanInTheLoopMiddleware`, `interrupt()` | `ui_prompt` / `task.tools.ui_prompt` confirmation (sign-off on each call), plus a credential policy scoped to the agent (who can call it) |
| Checkpointer, thread state | Guild session state; `task.save` / `task.restore` in TypeScript |
| `langgraph.json` `env` | Guild credentials (never `.env` values) |
| LangSmith tracing | Guild session event log (`GET /v1/sessions/{id}/events`), Insights |
| LangSmith datasets and evaluators | Guild Evaluations and `guild agent test` |
| LangSmith Deployment cron jobs | `guild trigger create --type time` |
| Agent Server API (`runs` endpoints) | `guild trigger create --type api` |
| Run webhooks (POST callback when a run finishes) | No trigger equivalent; have the agent call your service through an integration as its last step |
| Fleet Slack, Teams, Gmail, Outlook triggers | `guild trigger create --type webhook --integration <slack|gmail|…> …` |
| Fleet schedules | `guild trigger create --type time` |
| Fleet sharing (clone / run / edit) | Hub visibility (Draft, Internal, Public) and workspaces |
| `langgraph deploy` | `guild agent save --wait --publish` |

## Pitfalls

- Legacy APIs: `AgentExecutor` moved to `langchain-classic` in v1, which Guild's runtime does not install, and `langgraph.prebuilt.create_react_agent` is deprecated since v1. Upgrade to `create_agent` first.
- Any extra Python dependency (vector store clients, `requests`, provider SDKs) blocks Path A. Replace it with a Guild integration or move to TypeScript.
- `guild_tools()` is async, so the graph target must be an async factory.
- A LangGraph turn fails after 10 minutes without events; long-running nodes must call Guild tools or be split.

## Gaps

- Guild's LangGraph runtime is Python only and allows no extra packages; LangSmith Deployment allows arbitrary dependencies.
- LangSmith Deployment can self-host or run hybrid; Guild is hosted only.
- LangSmith evaluators, datasets, and Engine failure clustering have no 1:1 equivalent; port the key cases to Guild Evaluations.
- `interruptOn` and Fleet "Ask" become a credential policy scoped to the agent and workspace (who can call it) plus a `ui_prompt` confirmation before the call (sign-off on each call; the run pauses until someone answers).

# Runlayer → Guild

Runlayer is a commercial, proprietary enterprise AI control plane: MCP Gateway, Catalog, Runtime Security, Agent IAM & Governance, ROI & Observability, Shadow AI, and **Runlayer Agents** (governed agents created in its UI or from clients such as Slack, Microsoft Teams, Claude, Cursor, ChatGPT, and Codex). Facts as of 2026-10-27.

Sources: https://runlayer.com/llms.txt, https://docs.runlayer.com/llms.txt, https://docs.runlayer.com/platform-agents.md, https://docs.runlayer.com/platform-agent-accounts.md, https://docs.runlayer.com/platform-agents.md#human-in-the-loop-approvals, https://docs.runlayer.com/platform-agents-terraform.md, https://docs.runlayer.com/deployment/overview.md

## Detection signals

Runlayer agents live in Runlayer, not in a repository, so the input is usually one of:

- A `runlayer_agent` Terraform resource. It covers the prompt, model, connectors and tools, skills, env var names, and built-in tools, but not triggers, sharing, or approvals, and edits made in the app don't show up as drift. Read those from the agent's page in the app.
- The agent's fields copied from the UI: name, main prompt, privacy, built-in tools (memory, code mode), MCP connectors with selected tools, model, instructions, skills, env vars.
- Its triggers (cron schedule, webhook, API, Slack mention or channel monitor, Microsoft Teams, iMessage, audit-event trigger) and approvals.
- Subagents and allowed agents, the network access policy, GitHub access, and memory (workbench memory and scoped `remember`/`forget` memory).

Ask the user for these fields if they are not in the workspace. Never ask for secret values.

## Choosing the Guild type

Every Runlayer agent runs in a sandbox with shell, file, and browser tools, so decide by what the prompt relies on:

- Text in/out with tools → **Native** (`PROMPT.md` + `guild.yaml`).
- Code mode turned on, or a prompt that relies on shell commands, files in `/tmp/workspace`, the built-in or cloud browser, or GitHub access → **OpenClaw** (browser work also needs a browser integration).
- Needs typed I/O or deterministic steps → **TypeScript**.

## Concept map

| Runlayer | Guild |
|---|---|
| Main prompt + instructions | `PROMPT.md` (Native) or `AGENTS.md` (OpenClaw) |
| Model (Anthropic, OpenAI, Bedrock, Azure Foundry, Google AI Studio, OpenAI-compatible) | `guild.yaml` `models` fallback list |
| MCP connectors with per-tool selection | `guild.yaml` `integrations` with a `tools` list |
| Catalog / MCP Gateway servers | Guild integrations (catalog, `guild integration create`) |
| Skills | OpenClaw `skills/<name>/SKILL.md`, or Guild Hub skills |
| Env vars | Guild credentials (secrets) or workspace variables for settings (`guild workspace variable set KEY=value --workspace <owner~workspace>`) |
| Built-in memory | OpenClaw `MEMORY.md` (read-only per task) or TypeScript `task.save` / `task.restore` |
| Code mode / sandbox | OpenClaw shell, files, git |
| Cron schedule | `guild trigger create --type time --frequency CRON --cron-expression "<expr>" --cron-timezone <tz>` (converted to UTC) |
| Webhook trigger | `guild trigger create --type webhook` (integration events) or `--type api` |
| Slack mention | `guild trigger create --type webhook --integration slack --event app_mention` |
| Slack channel monitor (new top-level messages, optional semantic condition) | `guild trigger create --type webhook --integration slack --event message`, with the Slack agent invited to the monitored channels |
| Agent Accounts (on-behalf-of or machine-to-machine) | Member-scoped credentials + identity mapping, or agent-scoped credentials |
| Policies (server, tool, user, group, arguments) | Credential policies (ALLOW/DENY by operation, resource, agent, workspace) |
| Guarded tool calls (requester approves) | Credential policy scoped to the agent (who can call it) plus a `ui_prompt` confirmation (sign-off on each call) |
| Versioning on every save | `guild agent save` versions with semver (`--bump`) |
| Sharing (Can use / Can edit) | Workspaces and Hub visibility (Draft, Internal, Public) |
| Sessions, cost, budgets | Session event log, Spend Explorer, spend budgets |
| Agent Evals (replay with another model or prompt) | Guild Evaluations, `guild agent test` |

## Before / after

Runlayer agent (fields):

```text
Name: Incident scribe
Main prompt: When an incident channel opens, collect the timeline from Slack and PagerDuty and draft a postmortem in Notion.
Connectors: Slack (conversations.history), PagerDuty (incidents.get), Notion (pages.create)
Model: Claude
Trigger: Slack channel monitor on #incidents
```

Guild Native agent:

```markdown
<!-- PROMPT.md -->
You are Incident scribe. When asked about an incident, collect the timeline from the Slack channel
and the PagerDuty incident, then draft a postmortem page in Notion. Ask before creating the page.
```

```yaml
# guild.yaml
models:
  - provider: anthropic
integrations:
  - name: <owner>~pagerduty
    version: ^1.0.0
    tools: [pagerduty_incidents_get]
  - name: <owner>~notion
    version: ^1.0.0
    tools: [notion_pages_create]
builtins:
  - name: ui
    tools: [ui_prompt]
```

Slack history access depends on the live Slack integration schema; check `guild integration operation list guildai~slack --json`. Then:

```bash
guild agent init --name incident-scribe --agent-type GUILD_NATIVE --category <category> --owner <owner>
guild workspace variable set INCIDENT_CHANNEL=incidents --workspace <owner~workspace>
git add -A
guild agent test
```

## Pitfalls

- Runlayer connectors are MCP servers; Guild integrations are versioned packages with `{service}_{operation}` tool names. Map each selected tool explicitly.
- Runlayer schedules can run on local wall-clock time and as the schedule's creator; Guild triggers run with the credentials resolved for the workspace and agent. Re-check whose identity each action uses.
- Runlayer `schedule_continuation` (wait 1 minute to 24 hours) has no direct Guild equivalent; split into a scheduled trigger.

## Gaps

- Runlayer offers customer-hosted runtimes (ECS or Kubernetes); Guild is hosted only.
- Runlayer's ToolGuard/AgentGuard runtime scanners, Shadow AI discovery, and argument-level policies go beyond Guild credential policies. Both restrict egress: Runlayer with a per-agent network access policy, Guild by cutting container network access so only Guild proxies reach out.
- Microsoft Teams and iMessage triggers have no Guild trigger; check `guild integration list` first.
- Requester-only approvals with expiry windows (a pending request lapses after 24 hours) have no direct equivalent. Use a credential policy scoped to the agent and workspace (who can call it) plus a `ui_prompt` confirmation before the call (sign-off on each call; the run pauses until someone answers).
- Audit-event triggers with semantic conditions have no Guild equivalent.

# Arcade → Guild

Arcade (arcade.dev) is an "actions runtime" for AI agents: per-user OAuth for tools, a catalog of more than 100 integrations, MCP Gateways, tool-level policy hooks, an admin audit log, and `arcade evals` for tool selection. Tools are written in Python with the MIT-licensed `arcade-mcp` framework (`MCPApp`, `@app.tool(requires_auth=...)`). Arcade has **no agent runtime**: no hosted agents, sessions, triggers, schedules, or agent hub. Agents that use Arcade are built in another framework (such as LangChain, OpenAI Agents, Vercel AI SDK, Mastra, Google ADK, CrewAI, AG2, CopilotKit, or Spring AI) and call Arcade through `arcadepy` / `@arcadeai/arcadejs` or an MCP Gateway. Facts as of 2026-10-27.

Sources: https://www.arcade.dev/, https://docs.arcade.dev/llms.txt, https://github.com/ArcadeAI/arcade-mcp, https://docs.arcade.dev/en/references/mcp/python, https://docs.arcade.dev/en/references/auth-providers, https://docs.arcade.dev/en/operate/governance/mcp-gateways, https://docs.arcade.dev/en/operate/governance/contextual-access, https://docs.arcade.dev/en/resources/integrations, https://docs.arcade.dev/en/references/arcade-cli, https://www.arcade.dev/pricing

So an Arcade migration has two halves. Migrate the **agent** using the reference for its framework (`vercel-eve.md`, `langchain.md`, or plain code → TypeScript/Native). Map the **tools** with this reference.

## Detection signals

| Strength | Signal |
|---|---|
| Strong | `arcade-mcp`, `arcade-mcp-server`, or `arcadepy` in `pyproject.toml` / `requirements.txt`; `@arcadeai/arcadejs` in `package.json` |
| Strong | `from arcade_mcp_server import MCPApp, Context`; `@app.tool(requires_auth=GitHub())`; `requires_secrets=[...]` |
| Strong | `client.tools.execute(...)`, `client.tools.authorize(...)`, `client.auth.wait_for_completion(...)` / `waitForCompletion` |
| Supporting | `eval_*.py` importing `arcade_evals`; `ARCADE_API_KEY`, `ARCADE_BASE_URL`, `ARCADE_URL` in `.env.example`; `https://api.arcade.dev/mcp/<slug>` URLs; `Arcade-User-ID` header |
| Legacy | `arcade-tdk`, `arcade-ai`, `arcade-serve`, `langchain-arcade`, `agents-arcade` (deprecated or unmaintained); `from arcade_tdk import tool, ToolContext`; `worker.toml`; `engine.yaml` |

## Two migration paths

- **A. Replace Arcade.** Each Arcade toolkit becomes a Guild integration; custom `MCPApp` tools become a custom Guild integration; the agent runs on Guild. Choose this when the toolkits in use exist in the Guild catalog or can be added with `guild integration create`.
- **B. Keep Arcade as the tool layer.** Move only the agent to Guild and reach the Arcade MCP Gateway through a custom integration. **Verify first** that a Guild custom integration can front a remote Streamable HTTP MCP server. The gateway must use the **Arcade Headers** auth mode, which takes `Authorization: Bearer <API key>` and `Arcade-User-ID: <end user>`; the other modes (Arcade Auth, User Source) need a browser OAuth flow. Choose this when the agent depends on Arcade-only toolkits or per-end-user OAuth that Guild credentials do not cover.

## Concept map

| Arcade | Guild |
|---|---|
| Prebuilt toolkit (Gmail, Slack, GitHub, Linear, Notion, Google Calendar, …) | Guild integration from the catalog (`guild integration list`), tools named `{service}_{operation}` |
| Custom `MCPApp` server / `@app.tool` | Custom integration: `guild integration create` from an OpenAPI spec or MCP server |
| `requires_auth=<Provider>()` (per-user OAuth) | Integration credential; member-scoped for per-person access, plus identity mapping for Slack/GitHub-started runs |
| `requires_secrets=[...]` / `context.get_secret` | Guild credentials (the proxy injects them; the agent never sees values) or workspace variables |
| `user_id` passed per call | The Guild member or agent whose credential resolves for the session |
| `client.tools.authorize` + `wait_for_completion` (connect prompt) | Connect the credential in Guild once; the proxy injects it on every call |
| `client.tools.execute(tool_name=..., input=...)` in an agent loop | TypeScript `pick(<Integration>Tools, [...])` / `guildServiceTool(...)`, or `guild.yaml` `integrations` with a `tools` list |
| MCP Gateway (`api.arcade.dev/mcp/<slug>`) | Path A: integrations declared on the agent. Path B: a custom integration fronting the gateway (verify) |
| Contextual Access hooks (allow, deny, modify, redact) | Credential policies (ALLOW/DENY by operation, resource, agent, workspace); modify/redact has no equivalent |
| Tool grant / revoke / versioning | Integration versions pinned with semver ranges in `guild.yaml` or `package.json` |
| `arcade evals` (`eval_*.py`, `EvalSuite`, critics) | Guild Evaluations (`hasToolCall`, `toolCallContains`, `outputMatches`, `llmJudge`) and `guild agent test` |
| Tool execution records, admin audit log (REST API) | Session event log and the org audit log |
| `arcade deploy` (host an MCP server) | No equivalent: Guild hosts agents and brokers integrations, not arbitrary MCP servers |
| Self-hosted (cloud marketplace, Helm, VPC, air-gapped) | No equivalent: Guild is hosted only |

## Before / after: custom tool with `requires_auth`

Arcade `MCPApp` server:

```python
from typing import Annotated
from arcade_mcp_server import Context, MCPApp
from arcade_mcp_server.auth import GitHub

app = MCPApp(name="triage_tools", version="1.0.0")

@app.tool(requires_auth=GitHub(scopes=["repo"]))
async def comment_on_issue(
    context: Context,
    owner: Annotated[str, "Repository owner"],
    repo: Annotated[str, "Repository name"],
    issue_number: Annotated[int, "Issue number"],
    body: Annotated[str, "Comment text"],
) -> dict:
    """Post a triage comment on a GitHub issue."""
    token = context.get_auth_token_or_empty()
    ...  # httpx POST to api.github.com with the token
```

Guild TypeScript agent: the GitHub integration replaces the tool, and Guild injects the credential.

```ts
"use agent";
import { gitHubTools } from "@guildai-services/guildai~github";
import { agent, pick, type Task } from "@guildai/agents-sdk";
import { z } from "zod";

const inputSchema = z.object({
  owner: z.string(),
  repo: z.string(),
  issueNumber: z.number().int().positive(),
  body: z.string().max(4_000),
});
const outputSchema = z.object({ commented: z.boolean() });
const tools = { ...pick(gitHubTools, ["github_issues_create_comment"]) };

async function run(input: z.infer<typeof inputSchema>, task: Task<typeof tools>) {
  await task.tools.github_issues_create_comment({
    owner: input.owner,
    repo: input.repo,
    issue_number: input.issueNumber,
    body: input.body,
  });
  return { commented: true };
}

export default agent({
  description: "Posts a triage comment on a GitHub issue.",
  inputSchema,
  outputSchema,
  tools,
  run,
});
```

Check the exact operation input shape with `guild integration operation list guildai~github --json` before porting.

## Before / after: agent calling Arcade tools

Agent loop with `arcadepy` (OpenAI Agents or LangChain wraps the same calls):

```python
from arcadepy import Arcade

client = Arcade()  # ARCADE_API_KEY
auth = client.tools.authorize(tool_name="Gmail.ListEmails", user_id=user_email)
if auth.status != "completed":
    print("Authorize:", auth.url)
    client.auth.wait_for_completion(auth.id)
emails = client.tools.execute(
    tool_name="Gmail.ListEmails", input={"n_emails": 10}, user_id=user_email
).output.value
```

Guild Native agent:

```markdown
<!-- 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.
```

```yaml
# 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]
```

Native agents support only the `ui` built-in, so there is no connect step in the agent. Connect the Gmail credential in Guild once.

The Gmail integration and tool names above are the ones used by Guild agents in this repository today. Confirm them with `guild integration list` and `guild integration operation list guildlabs~gmail-oauth --json`. Then:

```bash
guild agent init --name inbox-digest --agent-type GUILD_NATIVE --category <category> --owner <owner>
git add -A
guild agent test
```

## Pitfalls

- In late October 2026, Arcade Cloud started running a release (previewed as 1.12.0) that renamed tools across most toolkits, with no aliases. Self-hosted installs get it in the next release. Map from the tool names the source code actually calls, not from current Arcade docs.
- Arcade's `user_id` is your app's end user; Guild credentials belong to Guild members, workspaces, or agents. A multi-tenant SaaS that authorizes thousands of its own customers through Arcade does not map to member-scoped credentials. Keep Arcade for that layer (path B) or redesign.
- Arcade Contextual Access can modify or redact tool inputs and outputs; Guild credential policies only allow or deny. Move modify/redact logic into the agent code.
- Arcade-managed OAuth apps are for development. Guild integrations use their own OAuth apps; users reconnect once in Guild.
- Python `MCPApp` tool code does not run inside a Guild agent. Rewrite the call against an integration, or publish the API as a custom integration (`guild integration create`).
- Catalog gaps: when no Guild integration exists for an Arcade toolkit, create one from the vendor's OpenAPI spec and diff `guild integration operation list --json` against the spec.

## Gaps

- No per-end-user OAuth for your own app's customers; Guild authorizes Guild members.
- No hosting of arbitrary MCP servers (`arcade deploy`).
- No self-hosted, cloud marketplace, VPC, or air-gapped deployment; Guild is hosted only.
- No modify/redact policy hooks on tool calls.
- No Tool Recommendation or MCP Gateway-style tool search across a large catalog.
- `arcade evals` suites do not run on Guild; rebuild them as Guild Evaluations.

# Guild target: primitives and CLI

The Guild side of every migration. Facts from docs.guild.ai and Guild CLI 0.27.2 and 0.28.0, as of 2026-10-23.

## Agent types

| Type | Files | Runtime | Pick it when |
|---|---|---|---|
| Native | `PROMPT.md`, `guild.yaml` | No container; ready immediately | Instructions plus tools, text in and text out |
| TypeScript | `agent.ts`, `package.json`, `tsconfig.json` (`guild.json` is CLI-managed) | Built and validated on save | Typed input/output, deterministic orchestration, attachments |
| Goose | `recipe.yaml`, `guild.yaml` | Container (`guildai~goosebox` by default) | Portable recipe with parameters and a response schema |
| OpenClaw | `AGENTS.md`, `guild.yaml`, optional `skills/<name>/SKILL.md`, `IDENTITY.md`, `USER.md`, `SOUL.md`, `MEMORY.md` | `guildai~lobsterpot` container with shell, file editing, git, search | Repository, file, or command work |
| LangGraph | `langgraph.json`, `graph.py`, `guild.yaml` | Python 3.13 container with `langchain`, `langchain-core`, `langchain-openai`, `langgraph`, `guildai_langchain` | A LangChain/LangGraph v1 graph with no extra pip packages |

Constraints that matter during a port:

- Native: no container, no filesystem, no custom input or output schemas, no attachments. Built-ins are `ui_prompt` and `ui_progress`.
- OpenClaw: the workspace is rebuilt from committed files on every task, so writes do not persist between tasks.
- LangGraph: no general network access; no extra packages; `AgentExecutor` is not installed (it moved to `langchain-classic`) and `create_react_agent` is deprecated, so use `create_agent`; a turn fails after 10 minutes without events (the clock pauses during Guild tool calls).
- Every type: tool names must be unique across integrations, sub-agents, and builtins; a public agent cannot depend on a private integration or sub-agent.

Sources: https://docs.guild.ai/guide/agent-types.md, https://docs.guild.ai/guide/native-agents.md, https://docs.guild.ai/guide/openclaw-agents.md, https://docs.guild.ai/guide/langgraph-agents.md

## `guild.yaml` (Native, Goose, OpenClaw, LangGraph)

TypeScript agents do not use `guild.yaml`.

```yaml
models:                     # ordered fallback list, max 16; first allowed entry wins
  - provider: anthropic
    model: claude-sonnet-5
  - provider: openai        # omit model to accept any model from the provider
integrations:
  - name: acme~github
    version: ^1.4.0
    tools: [github_repos_get, github_issues_list_for_repo]   # omit to allow every operation
sub_agents:
  - name: acme~research
    version: ^1.0.0
builtins:
  - name: ui
    tools: [ui_prompt]
  - name: console           # not available to Native agents
  - name: guild             # not available to Native agents
```

`environment` is Goose-only; declaring it on any other type is a build error. Providers: `anthropic`, `openai`, `gemini`, `meta`, `deepseek`, `alibaba`, `moonshot`, `zai`.

Source: https://docs.guild.ai/guide/guild-yaml.md

## TypeScript SDK shape

```ts
"use agent";
import { agent, consoleTools, pick, userInterfaceTools, type Task } from "@guildai/agents-sdk";
import { z } from "zod";
import { summarize } from "./logic.ts";

const description = "Summarizes open issues for a repository. Does not post anywhere.";
const inputSchema = z.object({ type: z.literal("text").optional(), text: z.string().max(8_000) });
const outputSchema = z.object({ summary: z.string() });

const tools = { ...pick(userInterfaceTools, ["ui_prompt"]), ...consoleTools };
type Tools = typeof tools;

async function run(input: z.infer<typeof inputSchema>, task: Task<Tools>): Promise<z.infer<typeof outputSchema>> {
  const result = await task.llm.generateText({ system: "Summarize briefly.", prompt: input.text });
  return { summary: summarize(result.text) };
}

export default agent({ description, inputSchema, outputSchema, tools, run });
```

Building blocks:

- `llmAgent({ description, tools, systemPrompt, mode })`: prompt-driven agent; `mode` is `"one-shot"` (default) or `"multi-turn"`.
- `agent({ description, inputSchema, outputSchema, tools, run })`: code-driven agent.
- `pick(toolSet, ["tool_name"])`: register only the operations used.
- `guildServiceTool(service, { description, inputSchema, outputSchema, endpoint, owner, versionNumber })`: one hand-declared integration operation (required for Slack).
- `guildAgentTool({ calls: "owner~agent", inputSchema, outputSchema })`: call another Guild agent as a tool.
- `task.tools.ui_prompt({ type: "text", text })`: pause for a human answer (needs `userInterfaceTools`).
- `task.llm.generateText({ system, prompt })`: model call through Guild.
- `task.gather([...])` / `task.gatherSettled([...])`: parallel calls, built inline.
- Integration packages: `@guildai-services/<owner>~<integration>`, for example `@guildai-services/guildlabs~gmail-oauth`.

`package.json` scripts follow `agents/expense-manager`: `build` (`tsc --build` + agent compiler + copy), `test` (`tsc --build && node --test logic.test.mjs`). `.npmrc` contains `@guildai:registry=https://app.guild.ai/npm/`.

## Credentials and policies

- Scopes: account, workspace, member, or dedicated to one agent. A credential can be granted to one installed agent.
- A credential proxy injects auth server-side; agents never see secret values. GitHub uses short-lived GitHub App tokens.
- Credential policies are ALLOW/DENY rules by operation, resource, agent, and workspace; DENY wins; new credentials start allow-all.

Sources: https://docs.guild.ai/platform/credentials.md, https://docs.guild.ai/platform/credential-policies.md

## Triggers

- Event (for example a Slack mention or a GitHub pull request), schedule, and API.
- `guild trigger create --frequency` accepts `HOURLY`, `DAILY`, `WEEKLY`, `MONTHLY`, and `CRON` (with `--cron-expression` and `--cron-timezone`, default UTC). A `CRON` schedule with a timezone, such as `Europe/Athens`, is converted to UTC.

Source: https://docs.guild.ai/platform/triggers.md

## CLI cheat sheet

```bash
guild auth login
guild workspace list
guild workspace select

# create
guild agent categories                                   # pick a category
guild agent init --name <name> --agent-type <GUILD_NATIVE|GUILD_TYPESCRIPT|GOOSE|OPENCLAW|LANGGRAPH|ADK> \
  --category <category> --owner <owner>
guild agent init --name <name> --fork <owner~agent> --category <category> --owner <owner>
guild agent init --name <name> --agent-type GUILD_TYPESCRIPT --template LLM \
  --category <category> --owner <owner>                  # or AUTO_MANAGED_STATE, BLANK

# integrations
guild integration list
guild integration operation list <owner~integration> --json
guild integration create <name> --base-url <url> --auth-scheme api-key --header-template "Authorization: Bearer {token}"
guild integration operation create <name> --openapi openapi.yaml
guild integration connect <owner~integration>

# test (guild agent test uploads only files git tracks)
git add -A
guild agent test
guild agent test --mode json --timeout 300
guild agent chat '<text or json>'

# ship (only when asked)
guild agent save --message "<summary>" --wait
guild agent save --message "<summary>" --wait --publish   # first save after init: add --force
guild api-key create --owner <owner> --name "Publish" --scopes agents:write   # for the Publish Agent to Guild Action
guild workspace agent add <owner~agent> --workspace <owner~workspace>
guild workspace chat --agent <owner~agent> --workspace <owner~workspace> --once "<request>"

# triggers (only when asked)
guild trigger create --workspace <owner~workspace> --type time --agent <owner~agent> \
  --frequency WEEKLY --time 08:00 --days-of-week MONDAY --input '{"type":"text","text":"Weekly run"}'
guild trigger create --workspace <owner~workspace> --type webhook --agent <owner~agent> \
  --integration slack --event app_mention --input '{"type":"text","text":"{webhook_payload}"}'
guild trigger create --workspace <owner~workspace> --type api --agent <owner~agent>
guild trigger list
```

CLI 0.28.0 `guild agent init --help` lists `GUILD_NATIVE`, `GUILD_TYPESCRIPT`, `GOOSE`, `OPENCLAW`, `LANGGRAPH`, and `ADK`. CLI 0.27.2 lists only `GUILD_TYPESCRIPT`, `GOOSE`, and `OPENCLAW`, and with `--template` it silently creates a TypeScript agent even when `OPENCLAW` is requested. Use CLI 0.28.0 or later (`npx @guildai/cli@latest agent init …`) and check `agent_type` in the generated `guild.json` before porting.