> ## 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 LangChain and LangGraph to Guild

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

LangChain and LangGraph are open-source agent libraries. LangSmith is LangChain's commercial platform for tracing, evals, deployment, and Fleet, its no-code agent builder. Guild runs **LangGraph v1 graphs natively**: a Python LangGraph agent keeps its graph and swaps in Guild's model and tools. JavaScript `createAgent` agents move to Guild TypeScript, and Fleet agents move to Guild Native.

## Who this is for

Teams with LangGraph agents on LangSmith Deployment or their own servers, `createAgent` agents in Node services, or Fleet agents, who want them on a shared Hub. On Guild, credentials stay behind a proxy and every run shows in one workspace.

## Concept map

| Guild | LangChain / LangGraph / LangSmith |
| - | - |
| [LangGraph agent](https://docs.guild.ai/guide/langgraph-agents.md) with `guild_model()` | `create_agent` (Python) |
| TypeScript `llmAgent` | `createAgent` (JS) |
| LangGraph agent unchanged, or TypeScript `agent` control flow | `StateGraph` nodes and edges |
| `guild_model()` or `guild.yaml` `models` | Model string (`anthropic:…`) |
| [Integrations](https://docs.guild.ai/integrations/overview.md) declared in `guild.yaml`, loaded with `guild_tools()` | `@tool` functions, MCP tools (`langchain-mcp-adapters` or `langchain.mcp`) |
| 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) | `humanInTheLoopMiddleware`, `interrupt()` |
| Guild session state | Checkpointer, thread state |
| [Credentials](https://docs.guild.ai/platform/credentials.md) | `langgraph.json` `env` |
| Session event log and Insights | LangSmith tracing |
| Guild Evaluations and `guild agent test` | LangSmith datasets and evaluators |
| Schedule [trigger](https://docs.guild.ai/platform/triggers.md) | Deployment cron jobs |
| [API trigger](https://docs.guild.ai/platform/api-triggers.md) | Agent Server API (`runs` endpoints) |
| [Native agent](https://docs.guild.ai/guide/native-agents.md) (`PROMPT.md` + `guild.yaml`) | Fleet agent |
| Event triggers on those integrations | Fleet Slack, Teams, Gmail, and Outlook triggers |
| Schedule trigger | Fleet schedules |
| `guild agent save --wait --publish` | `langgraph deploy` |

## Before you start

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

Upgrade to LangChain and LangGraph v1 first. `AgentExecutor` moved to `langchain-classic` in v1, which Guild's LangGraph runtime doesn't include. `create_react_agent` is deprecated in v1, so replace it with `create_agent` from `langchain.agents`.

## Inventory

* Graph entry points in `langgraph.json` and every node.
* Every tool and MCP server (`MultiServerMCPClient`, or `MCPAdapter` from `langchain.mcp`), and the service it reaches.
* Python dependencies beyond `langchain`, `langchain-core`, `langchain-openai`, and `langgraph`.
* Interrupt or human-in-the-loop points.
* Cron jobs, webhooks, and, for Fleet, triggers and connection identities ("Claws" use fixed credentials; "Assistants" and per-user connections act as the invoker).
* Environment variables, by name only.

## Steps

> [tab] Python LangGraph
>
> **1. Scaffold a LangGraph agent**
>
> ```bash theme={null}
> guild agent init --name issue-triage --agent-type LANGGRAPH \
>   --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`.
>
> The scaffold contains `langgraph.json`, `graph.py`, `guild.yaml`, `README.md`, and `.gitignore`.
>
> **2. Swap model and tools**
>
> ```python After: graph.py theme={null}
> 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.")
> ```
>
> ```python Before: graph.py theme={null}
> 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.")
> ```
>
> `guild_tools()` is async, so the graph target must be an async factory.
>
> **3. Declare tools in guild.yaml**
>
> ```yaml theme={null}
> integrations:
>   - name: guildai~github
>     version: ^1.0.0
>     tools: [github_issues_list_for_repo, github_issues_update]
> ```
>
> Keep `langgraph.json` targets as relative file paths: `{ "dependencies": ["."], "graphs": { "agent": "./graph.py:graph" } }`.
>
> **4. Test**
>
> ```bash theme={null}
> 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'".

> [tab] JS createAgent
>
> **1. Scaffold a TypeScript agent**
>
> ```bash theme={null}
> guild agent init --name support-agent --agent-type GUILD_TYPESCRIPT --template LLM \
>   --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`.
>
> **2. Port the agent**
>
> ```ts After: agent.ts theme={null}
> "use agent";
> import { llmAgent, pick, userInterfaceTools } from "@guildai/agents-sdk";
> import { ZendeskTools } from "@guildai-services/<owner>~zendesk";
>
> 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",
> });
> ```
>
> ```ts Before theme={null}
> 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 } })],
> });
> ```
>
> Use `agent({ ..., run })` instead when the graph has deterministic branches. Nodes become functions, and parallel branches become an inline `task.gather([...])`.
>
> The `ui_prompt` confirmation replaces `interruptOn` 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.
>
> **3. 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'".

> [tab] LangSmith Fleet
>
> **1. Scaffold a Native agent**
>
> ```bash theme={null}
> guild agent init --name inbox-assistant --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`.
>
> **2. Move instructions and connections**
>
> Copy the Fleet instructions into `PROMPT.md`. List each connection's tools under `integrations` in `guild.yaml`, and add `builtins: [{ name: ui, tools: [ui_prompt] }]` for any tool set to "Ask". Tell the agent in `PROMPT.md` to confirm with `ui_prompt` before it calls those tools. To control which agents can call a tool at all, add a [credential policy](https://docs.guild.ai/platform/credential-policies.md) rule scoped to the agent and workspace.
>
> **3. Test**
>
> ```bash theme={null}
> 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'".

Then publish and wire triggers:

```bash theme={null}
guild agent save --message "Port from LangGraph" --wait --publish
guild workspace agent add <owner~agent> --workspace <owner~workspace>
guild trigger create --workspace <owner~workspace> --type webhook --agent <owner~agent> \
  --integration github --event issues --action opened \
  --input '{"type":"text","text":"Triage this issue: {webhook_payload}"}'
```

> [!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

Remove provider API keys and LangSmith keys; Guild routes model calls through its own proxy. Recreate service tokens as [credentials](https://docs.guild.ai/platform/credentials.md). Fleet "Claws" map to workspace- or agent-scoped credentials, and "Assistants" and per-user connections map to member-scoped credentials. Restrict operations with [credential policies](https://docs.guild.ai/platform/credential-policies.md).

## What doesn't map 1:1

> [accordion] Extra Python packages
>
> Guild's LangGraph runtime provides Python 3.13 with `langchain`, `langchain-core`, `langchain-openai`, `langgraph`, and `guildai_langchain` only. A graph that needs other packages (vector store clients, `requests`, provider SDKs) must replace them with Guild integrations or move to TypeScript.

> [accordion] Network access
>
> The container has no general network access. Every outside call must go through a Guild tool.

> [accordion] Long turns
>
> A LangGraph turn fails after 10 minutes without events. The clock pauses during Guild tool calls.

> [accordion] Approval lists
>
> `interruptOn` and Fleet's per-tool "Ask" 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] Run webhooks
>
> LangSmith Deployment webhooks send a POST callback to your service when a run finishes. They notify, they don't start runs, so they have no Guild trigger equivalent. To notify a service when a Guild run ends, have the agent call it through an integration as its last step.

> [accordion] Self-hosting and hybrid
>
> LangSmith Deployment offers hybrid and self-hosted options. Guild is hosted only.

> [accordion] Evaluations
>
> LangSmith datasets, evaluators, and Engine have no 1:1 equivalent. Port your key cases to Guild Evaluations.

## Three ways to migrate

> [card] [guild-migrate skill](https://docs.guild.ai/migrations/guild-migrate-skill.md)
>
> Ask your coding agent: "Migrate this LangGraph project to Guild." It picks the LangGraph or TypeScript path 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/langchain/` in the guild-migrate repository.

## Related pages

> [card] [LangGraph agents](https://docs.guild.ai/guide/langgraph-agents.md)
>
> The runtime, `guild_model()`, `guild_tools()`, and constraints.

> [card] [guild.yaml](https://docs.guild.ai/guide/guild-yaml.md)
>
> Models, integrations, sub-agents, and builtins.