> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langchain.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Custom workflow
In the **custom workflow** architecture, you define your own bespoke execution flow using [LangGraph](/oss/javascript/langgraph/overview). You have complete control over the graph structure—including sequential steps, conditional branches, loops, and parallel execution.
```mermaid theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
graph LR
A([Input]) --> B{{Conditional}}
B -->|path_a| C[Deterministic step]
B -->|path_b| D((Agentic step))
C --> G([Output])
D --> G([Output])
classDef trigger fill:#F6FFDB,stroke:#6E8900,stroke-width:2px,color:#2E3900
classDef process fill:#E5F4FF,stroke:#006DDD,stroke-width:2px,color:#030710
classDef decision fill:#FDF3FF,stroke:#7E65AE,stroke-width:2px,color:#504B5F
class A,G trigger
class C,D process
class B decision
```
## Key characteristics
* Complete control over graph structure
* Mix deterministic logic with agentic behavior
* Support for sequential steps, conditional branches, loops, and parallel execution
* Embed other patterns as nodes in your workflow
## When to use
Use custom workflows when standard patterns (subagents, skills, etc.) don't fit your requirements, you need to mix deterministic logic with agentic behavior, or your use case requires complex routing or multi-stage processing.
Each node in your workflow can be a simple function, an LLM call, or an entire [agent](/oss/javascript/langchain/agents) with [tools](/oss/javascript/langchain/tools). You can also compose other architectures within a custom workflow—for example, embedding a multi-agent system as a single node.
For a complete example of a custom workflow, see the tutorial below.
The [router pattern](/oss/javascript/langchain/multi-agent/router) is an example of a custom workflow. This tutorial walks through building a router that queries GitHub, Notion, and Slack in parallel, then synthesizes results.
>
## Basic implementation
The core insight is that you can call a LangChain agent directly inside any LangGraph node, combining the flexibility of custom workflows with the convenience of prebuilt agents:
```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { z } from "zod";
import { createAgent } from "langchain";
import { StateGraph, START, END, StateSchema, MessagesValue } from "@langchain/langgraph";
const agent = createAgent({ model: "openai:gpt-4o", tools: [...] });
const AgentState = new StateSchema({
messages: MessagesValue,
query: z.string(),
});
const agentNode: GraphNode = (state) => {
// A LangGraph node that invokes a LangChain agent
const result = await agent.invoke({
messages: [{ role: "user", content: state.query }]
});
return { answer: result.messages.at(-1)?.content };
}
// Build a simple workflow
const workflow = new StateGraph(State)
.addNode("agent", agentNode)
.addEdge(START, "agent")
.addEdge("agent", END)
.compile();
```
## Example: RAG pipeline
A common use case is combining [retrieval](/oss/javascript/langchain/retrieval) with an agent. This example builds a WNBA stats assistant that retrieves from a knowledge base and can fetch live news.
The workflow demonstrates three types of nodes:
* **Model node** (Rewrite): Rewrites the user query for better retrieval using [structured output](/oss/javascript/langchain/structured-output).
* **Deterministic node** (Retrieve): Performs vector similarity search — no LLM involved.
* **Agent node** (Agent): Reasons over retrieved context and can fetch additional information via tools.
```mermaid theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
graph LR
A([Query]) --> B{{Rewrite}}
B --> C[(Retrieve)]
C --> D((Agent))
D --> E([Response])
classDef trigger fill:#F6FFDB,stroke:#6E8900,stroke-width:2px,color:#2E3900
classDef process fill:#E5F4FF,stroke:#006DDD,stroke-width:2px,color:#030710
class A,E trigger
class B,C,D process
```
You can use LangGraph state to pass information between workflow steps. This allows each part of your workflow to read and update structured fields, making it easy to share data and context across nodes.
```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { StateGraph, Annotation, START, END } from "@langchain/langgraph";
import { createAgent, tool } from "langchain";
import { ChatOpenAI, OpenAIEmbeddings } from "@langchain/openai";
import { MemoryVectorStore } from "@langchain/classic/vectorstores/memory";
import * as z from "zod";
const State = Annotation.Root({
question: Annotation(),
rewrittenQuery: Annotation(),
documents: Annotation(),
answer: Annotation(),
});
// WNBA knowledge base with rosters, game results, and player stats
const embeddings = new OpenAIEmbeddings();
const vectorStore = await MemoryVectorStore.fromTexts(
[
// Rosters
"New York Liberty 2024 roster: Breanna Stewart, Sabrina Ionescu, Jonquel Jones, Courtney Vandersloot.",
"Las Vegas Aces 2024 roster: A'ja Wilson, Kelsey Plum, Jackie Young, Chelsea Gray.",
"Indiana Fever 2024 roster: Caitlin Clark, Aliyah Boston, Kelsey Mitchell, NaLyssa Smith.",
// Game results
"2024 WNBA Finals: New York Liberty defeated Minnesota Lynx 3-2 to win the championship.",
"June 15, 2024: Indiana Fever 85, Chicago Sky 79. Caitlin Clark had 23 points and 8 assists.",
"August 20, 2024: Las Vegas Aces 92, Phoenix Mercury 84. A'ja Wilson scored 35 points.",
// Player stats
"A'ja Wilson 2024 season stats: 26.9 PPG, 11.9 RPG, 2.6 BPG. Won MVP award.",
"Caitlin Clark 2024 rookie stats: 19.2 PPG, 8.4 APG, 5.7 RPG. Won Rookie of the Year.",
"Breanna Stewart 2024 stats: 20.4 PPG, 8.5 RPG, 3.5 APG.",
],
[{}, {}, {}, {}, {}, {}, {}, {}, {}],
embeddings
);
const retriever = vectorStore.asRetriever({ k: 5 });
const getLatestNews = tool(
async ({ query }) => {
// Your news API here
return "Latest: The WNBA announced expanded playoff format for 2025...";
},
{
name: "get_latest_news",
description: "Get the latest WNBA news and updates",
schema: z.object({ query: z.string() }),
}
);
const agent = createAgent({
model: "openai:gpt-5.4",
tools: [getLatestNews],
});
const model = new ChatOpenAI({ model: "gpt-5.4" });
const RewrittenQuery = z.object({ query: z.string() });
async function rewriteQuery(state: typeof State.State) {
const systemPrompt = `Rewrite this query to retrieve relevant WNBA information.
The knowledge base contains: team rosters, game results with scores, and player statistics (PPG, RPG, APG).
Focus on specific player names, team names, or stat categories mentioned.`;
const response = await model.withStructuredOutput(RewrittenQuery).invoke([
{ role: "system", content: systemPrompt },
{ role: "user", content: state.question },
]);
return { rewrittenQuery: response.query };
}
async function retrieve(state: typeof State.State) {
const docs = await retriever.invoke(state.rewrittenQuery);
return { documents: docs.map((doc) => doc.pageContent) };
}
async function callAgent(state: typeof State.State) {
const context = state.documents.join("\n\n");
const prompt = `Context:\n${context}\n\nQuestion: ${state.question}`;
const response = await agent.invoke({
messages: [{ role: "user", content: prompt }],
});
return { answer: response.messages.at(-1)?.contentBlocks };
}
const workflow = new StateGraph(State)
.addNode("rewrite", rewriteQuery)
.addNode("retrieve", retrieve)
.addNode("agent", callAgent)
.addEdge(START, "rewrite")
.addEdge("rewrite", "retrieve")
.addEdge("retrieve", "agent")
.addEdge("agent", END)
.compile();
const result = await workflow.invoke({
question: "Who won the 2024 WNBA Championship?",
});
console.log(result.answer);
```
***
[Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
[Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/langchain/multi-agent/custom-workflow.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).