Multi-agent

• A single agent has too many tools and makes poor decisions about which to use.
• Context or memory grows too large for one agent to track effectively.
• Tasks require specialization (e.g., a planner, researcher, math expert).

​

Multi-agent patterns

​

Choosing a pattern

​

Customizing agent context

• Which parts of the conversation or state are passed to each agent.
• Specialized prompts tailored to subagents.
• Inclusion/exclusion of intermediate reasoning.
• Customizing input/output formats per agent.

​

Tool calling

1. The controller receives input and decides which tool (subagent) to call.
2. The tool agent runs its task based on the controller’s instructions.
3. The tool agent returns results to the controller.
4. The controller decides the next step or finishes.

​

Implementation

import { createAgent, tool } from "langchain";
import { z } from "zod";

const subagent1 = createAgent({...});

const callSubagent1 = tool(
  async ({ query }) => {
    const result = await subagent1.invoke({
      messages: [{ role: "user", content: query }]
    });
    return result.messages.at(-1)?.text;
  },
  {
    name: "subagent1_name",
    description: "subagent1_description",
    schema: z.object({
      query: z.string().describe("The query to to send to subagent1."),
    }),
  }
);

const agent = createAgent({
  llm: model,
  tools: [callSubagent1]
});

1. The main agent invokes call_subagent1 when it decides the task matches the subagent’s description.
2. The subagent runs independently and returns its result.
3. The main agent receives the result and continues orchestration.

​

Where to customize

1. Subagent name ("subagent1_name"): This is how the main agent refers to the subagent. Since it influences prompting, choose it carefully.
2. Subagent description ("subagent1_description"): This is what the main agent “knows” about the subagent. It directly shapes how the main agent decides when to call it.
3. Input to the subagent: You can customize this input to better shape how the subagent interprets tasks. In the example above, we pass the agent-generated query directly.
4. Output from the subagent: This is the response passed back to the main agent. You can adjust what is returned to control how the main agent interprets results. In the example above, we return the final message text, but you could return additional state or metadata.

​

Control the input to the subagent

• Modify the prompt – Adjust the main agent’s prompt or the tool metadata (i.e., sub-agent’s name and description) to better guide when and how it calls the subagent.
• Context injection – Add input that isn’t practical to capture in a static prompt (e.g., full message history, prior results, task metadata) by adjusting the tool call to pull from the agent’s state.

import { createAgent, tool, AgentState, ToolMessage } from "langchain";
import { Command } from "@langchain/langgraph";
import { z } from "zod";

// Example of passing the full conversation history to the sub agent via the state.
const callSubagent1 = tool(
  async ({query}) => {
    const state = getCurrentTaskInput<AgentState>();
    // Apply any logic needed to transform the messages into a suitable input
    const subAgentInput = someLogic(query, state.messages);
    const result = await subagent1.invoke({
      messages: subAgentInput,
      // You could also pass other state keys here as needed.
      // Make sure to define these in both the main and subagent's
      // state schemas.
      exampleStateKey: state.exampleStateKey
    });
    return result.messages.at(-1)?.content;
  },
  {
    name: "subagent1_name",
    description: "subagent1_description",
  }
);

​

Control the output from the subagent

• Modify the prompt – Refine the subagent’s prompt to specify exactly what should be returned.
  • Useful when outputs are incomplete, too verbose, or missing key details.
  • A common failure mode is that the subagent performs tool calls or reasoning but does not include the results in its final message. Remind it that the controller (and user) only see the final output, so all relevant info must be included there.
• Custom output formatting – adjust or enrich the subagent’s response in code before handing it back to the main agent.
  • Example: pass specific state keys back to the main agent in addition to the final text.
  • This requires wrapping the result in a Command (or equivalent structure) so you can merge custom state with the subagent’s response.

import { tool, ToolMessage } from "langchain";
import { Command } from "@langchain/langgraph";
import { z } from "zod";

const callSubagent1 = tool(
  async ({ query }, config) => {
    const result = await subagent1.invoke({
      messages: [{ role: "user", content: query }]
    });

    // Return a Command to update multiple state keys
    return new Command({
      update: {
        // Pass back additional state from the subagent
        exampleStateKey: result.exampleStateKey,
        messages: [
          new ToolMessage({
            content: result.messages.at(-1)?.text,
            tool_call_id: config.toolCall?.id!
          })
        ]
      }
    });
  },
  {
    name: "subagent1_name",
    description: "subagent1_description",
    schema: z.object({
      query: z.string().describe("The query to send to subagent1")
    })
  }
);

​

Handoffs

1. The current agent decides it needs help from another agent.
2. It passes control (and state) to the next agent.
3. The new agent interacts directly with the user until it decides to hand off again or finish.

​

Implementation (Coming soon)