LangChain + LangGraph

LangChain and LangGraph let you build function-calling and graph-based agent loops. xpander supplies the agent definition (instructions, skills, model, knowledge-base links), and your handler wires those fields into a native LangGraph flow. In the SDK, skills are exposed as tools, the name agent loops use for them. This SDK integration is optional: agents created in Xpander Chat or through the API run on Claude Code, Codex or OpenCode by default. The steps below run a native LangGraph ReAct loop whose skills, model and instructions come from the xpander agent definition.

What doesn’t come built in

Unlike the Agno path, LangChain doesn’t have a one-call shortcut for pulling everything in at once, so we grab the agent definition from xpander and pass the pieces into create_react_agent ourselves. It’s only a few extra lines, but a few capabilities aren’t auto-wired and you wire them in your graph:

Capability	How to wire it
Knowledge-base retrieval	Call `xpander_agent.knowledge_bases_retriever()` and wrap it as a LangChain `Tool` (or call it directly inside a node).
Session storage	Use LangGraph’s own checkpointer/state flow, or move to Agno if you want the managed session-storage path from `Backend.aget_args()`.
Automatic guardrails, context-optimization plumbing, and multi-agent team runtime wiring	Build those behaviors yourself in your graph, or switch to Agno.

Prerequisites

Complete the Quickstart. You should already have the CLI installed, xpander login completed, and a scaffolded agent project.
Python 3.12+ for local development.
An LLM provider key in your shell that matches your LangChain provider package. For example: OPENAI_API_KEY for langchain-openai, ANTHROPIC_API_KEY for langchain-anthropic.

1. Install

All packages below are required for the default OpenAI example.

# 1. Install xpander runtime and LangChain/LangGraph dependencies.
pip install \
    xpander-sdk \
    langchain \
    langchain-openai \
    langgraph \
    python-dotenv

# 2. Optional: swap provider package for your model vendor.
pip install langchain-anthropic
pip install langchain-ollama

2. Set up scaffolding

# Create an agent named "my-langchain-agent"
xpander agent new \
    --name "my-langchain-agent" \
    --framework "langchain" \
    --folder "."

These files get created:

./
│
├── xpander_handler.py        # Your @on_task entry point. The file you'll edit most.
├── xpander_config.json       # Agent ID, organization ID, API key, framework selection.
├── agent_instructions.json   # role / goal / general (the agent's system prompt).
├── requirements.txt          # Python dependencies.
└── .env                      # XPANDER_API_KEY, XPANDER_ORGANIZATION_ID, XPANDER_AGENT_ID.

`xpander_config.json` reference

xpander_config.json

{
  "agent_id": "agt_01H...",
  "organization_id": "org_01H...",
  "api_key": "xpd_...",
  "framework": "langchain"
}

3. Create task handler

The full pattern, wrapped in @on_task so xpander routes tasks to it:

xpander_handler.py

from dotenv import load_dotenv
load_dotenv()

from xpander_sdk import on_task, Task, Agents
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent


def system_prompt(instructions):
    # xpander instructions are structured (role, goal, general).
    # LangChain expects one system string.
    parts = []
    if instructions.general:
        parts.append(f"System: {instructions.general}")
    if instructions.goal_str:
        parts.append(f"Goals:\n{instructions.goal_str}")
    if instructions.role:
        parts.append("Instructions:\n" + "\n".join(f"- {r}" for r in instructions.role))
    return "\n\n".join(parts)


@on_task
async def handler(task: Task) -> Task:
    # 1. Load the agent definition from xpander.
    xpander_agent = await Agents(configuration=task.configuration).aget(agent_id=task.agent_id)

    # 2. Build a LangChain chat model from the configured model name.
    llm = ChatOpenAI(model=xpander_agent.model_name, temperature=0)

    # 3. Bind xpander tools as LangGraph-compatible callables.
    react_agent = create_react_agent(llm, xpander_agent.tools.functions)

    # 4. Run the ReAct loop.
    response = await react_agent.ainvoke({
        "messages": [
            ("system", system_prompt(xpander_agent.instructions)),
            ("user", task.to_message()),
        ]
    })

    # 5. Write result back so xpander can persist and display it.
    last = response["messages"][-1]
    task.result = last.content if hasattr(last, "content") else str(last)
    return task

Here’s what’s happening:

Agents(...).aget(agent_id=task.agent_id) returns a fully loaded agent object.
xpander_agent.model_name is used as the LLM model id in your LangChain client.
xpander_agent.tools.functions returns one callable per skill, with a payload schema signature and generated docstrings LangChain/LangGraph can use.
xpander_agent.instructions contains general, role, and goal fields so you can build the system prompt format your graph expects.
task.result = ... hands the output back to xpander for storage and UI/API visibility.

4. Edit the agent system prompt

agent_instructions.json contains the agent’s system prompt and maps directly to agent.instructions in code:

agent_instructions.json

{
  "role": [
    "You are a customer support assistant for Acme.",
    "Always confirm the customer's account ID before taking any action."
  ],
  "goal": [
    "Resolve the customer's issue in as few turns as possible.",
    "Escalate to a human if the request involves a refund over $500."
  ],
  "general": "Be concise, professional, and friendly. Never invent policy details; if you don't know something, say so and offer to escalate."
}

Save the file and the next xpander agent dev syncs it to the control plane.

5. Stream chunks from LangGraph (optional)

For streaming output, use an async generator handler that yields TaskUpdateEvent values:

xpander_handler.py (streaming variant)

from datetime import datetime, timezone
from xpander_sdk import on_task, Task, Agents, TaskUpdateEvent, TaskUpdateEventType
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent

@on_task
async def handler(task: Task):
    xpander_agent = await Agents(configuration=task.configuration).aget(agent_id=task.agent_id)
    llm = ChatOpenAI(model=xpander_agent.model_name, temperature=0)
    react_agent = create_react_agent(llm, xpander_agent.tools.functions)

    messages = [
        ("system", system_prompt(xpander_agent.instructions)),
        ("user", task.to_message()),
    ]

    final_content = ""
    async for chunk in react_agent.astream({"messages": messages}):
        if "agent" in chunk:
            for msg in chunk["agent"].get("messages", []):
                if hasattr(msg, "content") and msg.content:
                    final_content = msg.content
                    yield TaskUpdateEvent(
                        type=TaskUpdateEventType.Chunk,
                        task_id=task.id,
                        organization_id=task.organization_id,
                        time=datetime.now(timezone.utc),
                        data=msg.content,
                    )

    task.result = final_content
    yield TaskUpdateEvent(
        type=TaskUpdateEventType.TaskFinished,
        task_id=task.id,
        organization_id=task.organization_id,
        time=datetime.now(timezone.utc),
        data=task,
    )

This pattern is for the decorator’s streaming mode, which is served through POST /invoke as SSE output.

6. Filter skill outputs with schema enforcement (optional)

When a skill returns large payloads, open the skill in Xpander Chat and set a filter on its Output schema tab. Only the fields you keep reach your LangChain loop, which cuts token usage. The steps are on Output response filtering.

7. Test local development

Run the handler with the dev server. Tasks created from any channel (REST, Slack, Xpander Chat) route to your laptop:

# Starts the @on_task HTTP server and subscribes to xpander event stream.
xpander agent dev

Routing cloud traffic to a local instance is a preview feature.When a local instance is running via xpander agent dev, it takes over and all tasks route to your locally running agent instead. Only one can be active at a time.

For one-shot testing without a server:

# Calls your handler once and exits.
python3 xpander_handler.py \
    --invoke \
    --prompt "Quick test" \
    --output_format json \
    --output_schema '{"answer":"string"}'

--output_format and --output_schema are useful for testing structured output without changing the agent’s settings in the control plane.

Next steps

Pre-built skills

What goes into agent.tools.functions, and how catalog skills authenticate.

Custom skills

Wrap a private API as a skill with @register_tool.

Full LangChain example

A standalone runnable script you can copy.

SDK integrations overview

What is auto-wired vs. manual for each supported agent loop.

Overview

REST API - Conversations

REST API - Agents

REST API - Tasks

Agent Workspace

REST API - Knowledge

REST API - Skills

REST API - Workflows

REST API - Custom Functions

REST API - Scheduled Tasks

REST API - Self-Schedules

REST API - Misc

SDK: get started

SDK integrations

Memory

Knowledge

Channels and webhooks

Skills in code

Advanced

CLI Reference

SDK Reference

LangChain + LangGraph

What doesn’t come built in

Prerequisites

1. Install

2. Set up scaffolding

`xpander_config.json` reference

3. Create task handler

4. Edit the agent system prompt

5. Stream chunks from LangGraph (optional)

6. Filter skill outputs with schema enforcement (optional)

7. Test local development

Next steps

Pre-built skills

Custom skills

Full LangChain example

SDK integrations overview

​What doesn’t come built in

​Prerequisites

​1. Install

​2. Set up scaffolding

​xpander_config.json reference

​3. Create task handler

​4. Edit the agent system prompt

​5. Stream chunks from LangGraph (optional)

​6. Filter skill outputs with schema enforcement (optional)

​7. Test local development

​Next steps

Pre-built skills

Custom skills

Full LangChain example

SDK integrations overview

What doesn’t come built in

Prerequisites

1. Install

2. Set up scaffolding

`xpander_config.json` reference

3. Create task handler

4. Edit the agent system prompt

5. Stream chunks from LangGraph (optional)

6. Filter skill outputs with schema enforcement (optional)

7. Test local development

Next steps