Support for hierarchical / multi-level Deep Agents (agent-as-subagent) ?

[WarisBunglawala]

Hi

I wanted to ask whether DeepAgent currently supports (or plans to support) a hierarchical, multi-level deep agent structure, where agents themselves can act as sub-agents of a parent agent.

My use case looks roughly like this (user-defined and stored in DB):

Main Deep Agent
  - Tool 1
  - Tool 2
  - Sub Agent 1
  - Sub Agent 2
      - Sub Agent 1 of Sub Agent 2
      - Sub Agent 2 of Sub Agent 2
  - Sub Agent 3

And so on (Dynamic flow and can have multi level nested agents)

Key requirements:
The hierarchy is defined by the user and stored in a database
The structure is constructed at runtime but does not change during execution

I want the LLM planner to decide:
which tool to call
or which sub-agent to invoke next
I do not want to manually manage nodes/edges or orchestration logic

Ideally, sub-agents are exposed similarly to tools, so the planner can reason over them naturally

Is there an existing pattern, recommended approach, or planned feature in DeepAgent to support agent-as-tool / agent-as-subagent hierarchies like this?

Example I tested

Below is a simplified example of how I tried to model this:

const subAgent1 = {
  name: "SOME NAME 1",
  tools: [tool1_1, tool1_2],
};

const subAgent3 = {
  name: "SOME NAME 3",
  tools: [tool3_1, tool3_2],
};

const subAgent2_1 = {
  name: "SOME NAME 2-1",
  tools: [tool2_1, tool2_2],
};

const subAgent2_2 = {
  name: "SOME NAME 2-2",
  tools: [tool2_3, tool2_4],
};

const subAgent2 = createDeepAgent({
  subAgents: [subAgent2_1, subAgent2_2],
});

const mainAgent = createDeepAgent({
  subAgents: [subAgent1, subAgent2, subAgent3],
});

Thanks!

[christian-bromann]

Warisahmed Bunglawala (@WarisBunglawala) I raised a PR with #207 to verify this use case works. I only made a small type fix but generally I assume this should already work today. Do you experience any issues? Mind taking a look at the example I added in the PR, does this match what you were looking for?

[WarisBunglawala]

Thanks for the quick response. Yes — to some extent this works as I expected, but there’s still an important piece missing (or I may be misunderstanding it). I’d appreciate some guidance here.

I reviewed your example and implemented my setup in the same way. That part is working: I can now use Deep Agents as sub-agents of a parent Deep Agent, even recursively.

However, what’s missing for my use case is how to pass invocation-specific context and parameters to sub deep agents.

When we call parentDeepAgent.invoke(...), we can pass things like:

recursion limits

run-specific context

other execution parameters

Example:

mainDeepAgent.invoke(
  {
    messages: [new HumanMessage("What's the weather in San Francisco?")],
  },
  {
    context: {
      key1,
      key2,
    },
  }
);

This context is accessible inside tools and sub deep agents, which is great.
But for sub deep agents, we never explicitly call .invoke() ourselves — they are triggered internally by the planner.

So my questions are:

How can we pass context or execution parameters that are specific to a sub deep agent, rather than inheriting everything from the parent?

Is there a supported way to differentiate context per sub agent run?

How can we reliably identify which sub agent initiated a tool call, especially when:

the same tool is shared between the parent and multiple sub agents, or

tools are reused across different levels of the hierarchy?

To illustrate, imagine a hierarchy like this (dynamic in depth):

Main Deep Agent
├─ Tool 1
├─ Sub Deep Agent 1
│   ├─ Tool 1
│   ├─ Sub Agent 1 of Sub Deep Agent 1

In this setup:

Parent context is inherited everywhere

But I don’t have control over .invoke() for sub deep agents

Which makes it hard to pass agent-specific context or execution options

And hard to reason about tool ownership when tools are shared

Is there an intended pattern for this, or is sub-agent-specific invocation context not supported yet?

[christian-bromann]

Warisahmed Bunglawala (@WarisBunglawala) these are great questions, let me walk through them:

What Already Works: Parent Context Flows to Sub-Agents. When you call parentDeepAgent.invoke() with a context, that context already propagates to all sub-agents automatically. The task tool passes the parent's full config (which includes context) directly to subagent.invoke():

// Internal: how the task tool invokes sub-agents today
const result = await subagent.invoke(subagentState, config);
//                                                   ^^^^^^
//                              parent's config (including context) is passed through

This means any tool inside a sub-agent can already access the parent's context via config.context (or runtime.context in middleware):

const myTool = tool(
  (input, config) => {
    const userId = config.context?.userId; // works in sub-agents too
    return `Hello user ${userId}`;
  },
  { name: "greet", schema: z.object({}), description: "Greet the user" }
);

// Parent invocation — context flows to all sub-agents and their tools
mainDeepAgent.invoke(
  { messages: [new HumanMessage("...")] },
  { context: { userId: "user-123", apiKey: "sk-..." } }
);

So for your first question: shared, read-only context that all agents need (like user ID, API keys, session info) — this already works today. Just define a contextSchema on the parent agent and pass context at invocation time.

What's Missing

You're right that there's currently no way to:

1. Pass context specific to a particular sub-agent (e.g., different roles or config per sub-agent)
2. Identify which sub-agent initiated a tool call when the same tool is shared across agents

I will discuss this with the team and will get back to you.

[christian-bromann]

Hey Warisahmed Bunglawala (@WarisBunglawala), following up on this — we've made progress on both points I mentioned were missing.

1. Per-subagent context

Since all subagents inherit the parent's full context, you can use namespaced keys to pass configuration specific to individual subagents. Prefix context keys with the subagent's name:

mainDeepAgent.invoke(
  { messages: [new HumanMessage("Research this and verify the claims")] },
  {
    context: {
      userId: "user-123",                        // shared by all agents
      "researcher:maxDepth": 3,                  // only for researcher
      "fact-checker:strictMode": true,           // only for fact-checker
    },
  },
);

Then read the relevant keys inside tools using the agent's identity (see below):

const verifyClaim = tool(
  (input, config) => {
    const strictMode = config.context?.["fact-checker:strictMode"] ?? false;
    if (strictMode) {
      return strictVerification(input.claim);
    }
    return basicVerification(input.claim);
  },
  {
    name: "verify_claim",
    description: "Verify a factual claim",
    schema: z.object({ claim: z.string() }),
  }
);

2. Identifying which subagent initiated a tool call

We found that the JS createAgent was not propagating lc_agent_name in config metadata — unlike the Python version which does this. We are fixing this (langchain-ai/langchainjs#9996, #218), so now when the same tool is shared between the parent and multiple subagents, you can use config.metadata?.lc_agent_name to determine which agent made the call:

const sharedLookup = tool(
  (input, config) => {
    const agentName = config.metadata?.lc_agent_name;
    if (agentName === "fact-checker") {
      return strictLookup(input.query);
    }
    return generalLookup(input.query);
  },
  {
    name: "shared_lookup",
    description: "Look up information from various sources",
    schema: z.object({ query: z.string() }),
  }
);

You can combine both patterns — use namespaced context for agent-specific configuration and lc_agent_name for branching tool behavior:

const flexibleSearch = tool(
  (input, config) => {
    const agentName = config.metadata?.lc_agent_name ?? "unknown";
    const ctx = config.context ?? {};

    const maxResults = ctx[`${agentName}:maxResults`] ?? 5;
    const includeRaw = ctx[`${agentName}:includeRaw`] ?? false;

    return performSearch(input.query, { maxResults, includeRaw });
  },
  {
    name: "flexible_search",
    description: "Search with agent-specific settings",
    schema: z.object({ query: z.string() }),
  }
);

So for your hierarchy example:

Main Deep Agent
├─ Tool 1  (agentName = "main-agent" or your parent's name)
├─ Sub Deep Agent 1
│   ├─ Tool 1  (agentName = "sub-agent-1")
│   ├─ Sub Agent 1 of Sub Deep Agent 1
│       ├─ Tool 1  (agentName = "nested-agent")

Each level's tools can read config.metadata?.lc_agent_name to know exactly which agent invoked them, and config.context to access both shared and agent-specific configuration.

Let me know if this covers your use case.

[WarisBunglawala]

Hi Christian Bromann (@christian-bromann)

Thanks for the guidance. I tried accessing lc_agent_name with latest release, but whenever a parent agent name is present, it always returns the parent name.

For example:

Main Deep Agent
├─ Tool 1  (agentName = "main-agent")
├─ Sub Deep Agent 1
│   ├─ Tool 2  (agentName = "sub-agent-1")
│   ├─ Sub Agent 1 of Sub Deep Agent 1
│       ├─ Tool 3  (agentName = "nested-agent")

However, when Tool 3 is called from Sub Agent 1 of Sub Deep Agent 1, the lc_agent_name is still reported as "main-agent".

Because of this behavior, I’m unable to use the suggested namespaced context for agent-specific configuration.

Could you please take a look into it? It has become a blocker for my system. Thanks.