> ## 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.
# LangGraph agents
> Run a LangGraph or LangChain agent written in Python on Guild, with Guild's models and tools built in.
A LangGraph agent is a Python [LangGraph](https://github.com/langchain-ai/langgraph) project: a `langgraph.json` manifest naming a graph in your committed source, the same layout `langgraph dev` accepts. Guild runs the graph in a container, routes its model calls through Guild, and gives it the Guild tools you declare. Agents built with LangChain's `create_agent` are LangGraph graphs, so they run the same way.
Use this agent type when you already write agents with LangChain or LangGraph, or when you want to control the orchestration yourself in Python.
LangGraph agents support LangChain and LangGraph v1 (`langchain>=1.0`, `langgraph>=1.0`). Pre-v1 APIs such as `AgentExecutor` and `create_react_agent` no longer exist. Use `create_agent` from `langchain.agents`.
## Create a LangGraph agent
```bash theme={null}
guild agent init --name my-langgraph-agent --agent-type langgraph
```
The scaffold includes:
```text theme={null}
my-agent/
├── langgraph.json # Names the graph to run
├── graph.py # The graph
├── guild.yaml # Integrations, sub-agents, and built-in tools
├── README.md
└── .gitignore
```
Edit `graph.py`, then save and run the agent like you would any other Guild agent.
1. Open **Agents** in the left nav, click **Your agents**, then click **Create Agent**.
2. Under **Or start another way**, choose **Start with code**.
3. Choose **LangGraph Agent**.
4. Edit `graph.py`.
The scaffolded `graph.py` is a working agent with no tools:
```python theme={null}
from guildai_langchain import guild_model
from langchain.agents import create_agent
graph = create_agent(
guild_model(),
tools=[],
system_prompt="You are my-agent, an agent running on the Guild platform.",
)
```
## The manifest
`langgraph.json` at the root of the agent's files names the graph Guild runs:
```json theme={null}
{
"dependencies": ["."],
"graphs": {
"agent": "./graph.py:graph"
}
}
```
* **`graphs`** is required. Each target is a relative path to a committed `.py` file, a colon, and an attribute name, such as `./my_agent/graph.py:graph`. Module-style targets (`my_agent.graph:graph`) are not supported.
* When `graphs` declares several graphs, Guild runs the one named `agent`. When it declares one, Guild runs that one.
* **`dependencies`** is optional. See [Dependencies](#dependencies).
The target can be any of these:
* A compiled graph, such as the one `create_agent` returns
* An uncompiled `StateGraph`. Guild compiles it.
* A function that takes no arguments and returns either of the above. It can be `async`. Use this form when the graph needs [Guild tools](#tools).
## Models
`guild_model()` returns a LangChain chat model whose calls go through Guild's LLM proxy. You don't configure a key or a URL. Guild picks the provider and model from the account's [LLM settings](/platform/llm-settings), so the model name you pass is only a hint. Extra keyword arguments pass through to the underlying `ChatOpenAI`.
Guild also points the OpenAI client environment at its proxy before your code loads, so a plain `ChatOpenAI()` is routed the same way. Either way, every call is metered and recorded in [Usage](/insights/usage), and the account's [model policies](/platform/llm-settings#model-policies) apply.
To declare the models the agent prefers, add a `models` section to `guild.yaml`. It works as it does for Goose agents — see [Models field](/guide/goose-agents#models-field).
## Tools
The integrations, sub-agents, and built-in tools the agent can call are declared in `guild.yaml` at the root of the agent's files, exactly as they are for [Goose agents](/guide/goose-agents#integrations-and-sub-agents-guild-yaml):
```yaml theme={null}
integrations:
- name: acme~github
version: ^1.4.0
tools: [github_repos_get, github_issues_list]
sub_agents:
- name: acme~research
version: ^1.0.0
builtins:
- name: ui
tools: [ui_prompt]
```
Omit `guild.yaml` when the agent needs none of them. `guild_tools()` returns the declared tools as ordinary LangChain tools. It's `async`, so make the graph target a factory that awaits it:
```python 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())
```
Each call runs as a sub-task on Guild: the credential is added server-side, and the call is recorded like any other agent's. A call that waits, such as a sub-agent or `ui_prompt`, can stay open for up to 30 minutes.
The built-in services available to a LangGraph agent are:
| Service | Tool | Behavior |
| - | - | - |
| `console` | `console_log` | Logs a message to the debug console. Does not suspend the task. |
| `ui` | `ui_prompt` | Prompts the user for additional information or clarification. Suspends the task. |
| `guild` | `guild_credentials_request` | Requests that the user configure credentials for a specific integration. Suspends the task. |
The field rules and validation for `integrations`, `sub_agents`, and `builtins` are the same as for Goose agents. The `environment` field is not supported. Declaring it, or any other section a LangGraph agent does not support, is a build error.
`guild_tools()` works only inside a Guild task. Calling it elsewhere, such as under `langgraph dev`, raises a `RuntimeError`.
## Input and output
LangGraph agents take text in and return text out. Guild applies these input and output schemas at build time.
* **Input** — each turn's text arrives as a `HumanMessage` appended to the graph's `messages`. The graph must accept `{"messages": [...]}`, as `create_agent` and any `MessagesState` graph do. A graph with a custom state schema fails its first turn.
* **Conversation** — Guild saves the message history in the task's state between turns, so a follow-up message in the same session continues the conversation.
* **Output** — the text of the model's last response in the turn. If the model produced no text, the output says so.
While a turn runs, the session shows the model's text as it streams, and each tool call as a progress line.
## Dependencies
The runtime image provides Python 3.13 with `langchain`, `langchain-core`, `langchain-openai`, and `langgraph`, plus the `guildai_langchain` bindings. Other packages can't be installed yet. Listing one under `dependencies` in `langgraph.json` is a build error. Local paths such as `"."` are allowed.
The container has no general network access. Reach outside services through Guild tools.
## Limits
* **Idle turns** — a turn fails if the graph produces no events for 10 minutes. The clock pauses while a Guild tool call is in flight, so a long sub-agent call or a wait on `ui_prompt` doesn't count.
* **Import errors** — the build checks the manifest but doesn't import your code. A syntax error, or a graph that can't be built, fails the first turn that runs it. Test with `guild agent test` or `guild agent chat` before you publish.
## Build-time validation
Guild validates the agent when you save a version. The manifest is checked first, because a manifest that can't resolve to a graph fails the build before any tool validation runs:
1. **Validate LangGraph manifest** — `langgraph.json` is present and valid, every graph target points to a committed `.py` file inside the workspace with a valid attribute name, a graph named `agent` exists when there are several, and every dependency is available.
2. **Parse guild.yaml** — `guild.yaml` is valid YAML, with no unknown keys and only sections a LangGraph agent supports.
3. **Validate Guild integrations** — each integration resolves to a published version, and any listed tools map to real operations on it.
4. **Validate Guild subagents** — each sub-agent resolves to a published version.
5. **Validate Guild builtins** — each service is one of `console`, `ui`, or `guild`, and each listed tool is permitted for that service.
6. **Validate LLM models** — each entry under `models` names a supported provider.
7. **Store Guild configuration** — the resolved tool manifest is recorded on the version.
A public agent cannot depend on a private integration or a private sub-agent. See [Versions](/guide/versions) for the full dependency visibility rules.