chore(deepagents): verify we can run nested deepagents (#207)

Author: christian-bromann

examples/hierarchical/hierarchical-agent.ts

@@ -0,0 +1,189 @@
+/* eslint-disable no-console */
+/**
+ * Hierarchical Deep Agent Example
+ *
+ * Demonstrates multi-level agent hierarchies where a deep agent acts as a
+ * subagent of another deep agent. This pattern enables:
+ *
+ * - **Agent-as-subagent**: A full `createDeepAgent` can be used as a
+ *   `CompiledSubAgent` in a parent agent
+ * - **Multi-level nesting**: Sub-agents can themselves have sub-agents,
+ *   creating arbitrarily deep hierarchies
+ * - **LLM-driven orchestration**: The parent agent's LLM planner decides
+ *   when to invoke a sub-agent vs. using a tool directly
+ *
+ * Architecture:
+ * ```
+ * Main Agent (orchestrator)
+ *   ├── Tool: get_weather
+ *   └── Sub Agent: research-specialist (DeepAgent)
+ *       ├── Tool: get_news
+ *       ├── Tool: analyze_data
+ *       └── Sub Agent: fact-checker (simple SubAgent)
+ *           └── Tool: verify_claim
+ * ```
+ *
+ * @see https://github.com/anthropics/deepagentsjs/issues/206
+ */
+import { tool } from "langchain";
+import { z } from "zod";
+import { HumanMessage } from "@langchain/core/messages";
+
+import {
+  createDeepAgent,
+  type CompiledSubAgent,
+  type SubAgent,
+} from "deepagents";
+
+// ─── Tools ──────────────────────────────────────────────────────────────────
+const getWeather = tool(
+  (input) => `The weather in ${input.location} is sunny and 72°F.`,
+  {
+    name: "get_weather",
+    description: "Get the current weather for a location",
+    schema: z.object({
+      location: z.string().describe("The city or location to get weather for"),
+    }),
+  },
+);
+
+const getNews = tool(
+  (input) =>
+    `Latest news for "${input.topic}":\n` +
+    `1. Major breakthrough in ${input.topic} announced today\n` +
+    `2. Experts weigh in on the future of ${input.topic}\n` +
+    `3. New study reveals surprising findings about ${input.topic}`,
+  {
+    name: "get_news",
+    description: "Search for the latest news articles on a topic",
+    schema: z.object({
+      topic: z.string().describe("The topic to search news for"),
+    }),
+  },
+);
+
+const analyzeData = tool(
+  (input) =>
+    `Analysis of "${input.data}":\n` +
+    `The data shows a positive trend with key insights:\n` +
+    `- Primary finding: significant growth in the area\n` +
+    `- Secondary finding: emerging patterns suggest continued development\n` +
+    `- Recommendation: further investigation warranted`,
+  {
+    name: "analyze_data",
+    description: "Analyze provided data and return insights",
+    schema: z.object({
+      data: z.string().describe("The data or topic to analyze"),
+    }),
+  },
+);
+
+const verifyClaim = tool(
+  (input) =>
+    `Verification of "${input.claim}":\n` +
+    `Status: ${input.claim.length > 20 ? "Partially verified" : "Verified"}\n` +
+    `Confidence: High\n` +
+    `Sources: 3 independent sources confirmed`,
+  {
+    name: "verify_claim",
+    description: "Verify a factual claim against known sources",
+    schema: z.object({
+      claim: z.string().describe("The claim to verify"),
+    }),
+  },
+);
+
+// ─── Level 2 Sub-Agent: Fact Checker (simple SubAgent within the research agent) ─
+const factCheckerSubAgent: SubAgent = {
+  name: "fact-checker",
+  description:
+    "A fact-checking agent that can verify claims. " +
+    "Use this when you need to validate specific facts or statements.",
+  systemPrompt:
+    "You are a fact-checking specialist. Use the verify_claim tool to check " +
+    "the accuracy of any claims or statements you receive. Always verify before " +
+    "drawing conclusions.",
+  tools: [verifyClaim],
+};
+
+// ─── Level 1 Sub-Agent: Research Specialist (itself a DeepAgent) ─────────────
+/**
+ * This deep agent acts as a sub-agent of the main agent.
+ * It has its own tools, sub-agents, and full agent capabilities including
+ * filesystem, todo management, and summarization.
+ */
+const researchDeepAgent = createDeepAgent({
+  systemPrompt:
+    "You are a research specialist. Your role is to gather news, analyze data, " +
+    "and produce well-researched findings.\n\n" +
+    "When asked to research a topic:\n" +
+    "1. Use the get_news tool to gather the latest information\n" +
+    "2. Use the analyze_data tool to analyze the findings\n" +
+    "3. If you need to verify specific claims, delegate to the fact-checker sub-agent\n" +
+    "4. Write a concise summary of your research findings",
+  tools: [getNews, analyzeData],
+  subagents: [factCheckerSubAgent],
+});
+
+// ─── Level 0: Main Orchestrator Agent ────────────────────────────────────────
+
+/**
+ * The main agent orchestrates between its own tools and sub-agents.
+ * The LLM decides whether to:
+ * - Use get_weather directly for weather queries
+ * - Delegate to the research-specialist deep agent for research tasks
+ */
+export const mainAgent = createDeepAgent({
+  systemPrompt:
+    "You are a helpful assistant that coordinates different capabilities.\n\n" +
+    "- For weather queries, use the get_weather tool directly\n" +
+    "- For research, analysis, or news queries, delegate to the research-specialist " +
+    "sub-agent which has specialized tools for these tasks\n\n" +
+    "Always choose the most appropriate tool or sub-agent for each task.",
+  tools: [getWeather],
+  subagents: [
+    {
+      name: "research-specialist",
+      description:
+        "A specialized research agent with its own tools and sub-agents. " +
+        "It can search for news, analyze data, and verify facts. " +
+        "Use this for any research, analysis, or investigation tasks.",
+      runnable: researchDeepAgent,
+    } satisfies CompiledSubAgent,
+  ],
+});
+
+// ─── Run ─────────────────────────────────────────────────────────────────────
+console.log("=== Hierarchical Deep Agent Example ===\n");
+
+// Test 1: Direct tool use (weather) — main agent handles this itself
+console.log("--- Query 1: Direct tool use (weather) ---");
+const result1 = await mainAgent.invoke({
+  messages: [new HumanMessage("What's the weather in San Francisco?")],
+});
+const lastMsg1 = result1.messages[result1.messages.length - 1];
+console.log(
+  "Response:",
+  typeof lastMsg1.content === "string"
+    ? `${lastMsg1.content.slice(0, 200)}...`
+    : lastMsg1.content,
+);
+
+// Test 2: Delegate to research sub-agent (DeepAgent)
+console.log("\n--- Query 2: Delegate to research sub-agent ---");
+const result2 = await mainAgent.invoke({
+  messages: [
+    new HumanMessage(
+      "Research the latest developments in renewable energy and provide an analysis.",
+    ),
+  ],
+});
+const lastMsg2 = result2.messages[result2.messages.length - 1];
+console.log(
+  "Response:",
+  typeof lastMsg2.content === "string"
+    ? `${lastMsg2.content.slice(0, 200)}...`
+    : lastMsg2.content,
+);
+
+console.log("\n=== Done ===");

libs/deepagents/src/agent.int.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect } from "vitest";
 import { AIMessage, HumanMessage } from "@langchain/core/messages";
 import { createDeepAgent } from "./index.js";
+import type { CompiledSubAgent } from "./index.js";
 import {
   SAMPLE_MODEL,
   TOY_BASKETBALL_RESEARCH,
@@ -288,6 +289,122 @@ describe("DeepAgents Integration Tests", () => {
     },
   );
 
+  it.concurrent(
+    "should use a deep agent as a compiled subagent (agent-as-subagent hierarchy)",
+    { timeout: 120 * 1000 }, // 120s
+    async () => {
+      // Create a deep agent that will serve as a subagent
+      const weatherDeepAgent = createDeepAgent({
+        model: SAMPLE_MODEL,
+        systemPrompt:
+          "You are a weather specialist. Use the get_weather tool to get weather information for any location requested.",
+        tools: [getWeather],
+      });
+
+      // Use the deep agent as a CompiledSubAgent in the parent
+      const parentAgent = createDeepAgent({
+        model: SAMPLE_MODEL,
+        systemPrompt:
+          "You are an orchestrator. Delegate weather queries to the weather-specialist subagent via the task tool.",
+        subagents: [
+          {
+            name: "weather-specialist",
+            description:
+              "A specialized weather agent that can provide detailed weather information for any city.",
+            runnable: weatherDeepAgent,
+          } satisfies CompiledSubAgent,
+        ],
+      });
+      assertAllDeepAgentQualities(parentAgent);
+
+      // Verify the task tool lists the weather-specialist subagent
+      const tools = extractToolsFromAgent(parentAgent);
+      expect(tools.task).toBeDefined();
+      expect(tools.task.description).toContain("weather-specialist");
+
+      // Invoke and verify the parent delegates to the weather-specialist
+      const result = await parentAgent.invoke(
+        {
+          messages: [new HumanMessage("What is the weather in Tokyo?")],
+        },
+        { recursionLimit: 100 },
+      );
+
+      const agentMessages = result.messages.filter(AIMessage.isInstance);
+      const toolCalls = agentMessages.flatMap((msg) => msg.tool_calls || []);
+
+      expect(
+        toolCalls.some(
+          (tc) =>
+            tc.name === "task" &&
+            tc.args?.subagent_type === "weather-specialist",
+        ),
+      ).toBe(true);
+    },
+  );
+
+  it.concurrent(
+    "should support multi-level deep agent hierarchy (nested deep agents)",
+    { timeout: 120 * 1000 }, // 120s
+    async () => {
+      // Level 2: A deep agent with its own subagents
+      const innerDeepAgent = createDeepAgent({
+        model: SAMPLE_MODEL,
+        systemPrompt:
+          "You are a sports information agent. Use the get_soccer_scores tool to get soccer scores.",
+        tools: [getSoccerScores],
+        subagents: [
+          {
+            name: "weather-helper",
+            description: "Gets weather information for match day conditions.",
+            systemPrompt:
+              "Use the get_weather tool to get weather information.",
+            tools: [getWeather],
+            model: SAMPLE_MODEL,
+          },
+        ],
+      });
+
+      // Level 1: Parent deep agent using the inner deep agent as a subagent
+      const parentAgent = createDeepAgent({
+        model: SAMPLE_MODEL,
+        systemPrompt:
+          "You are an orchestrator. Use the sports-info subagent for any sports related questions.",
+        tools: [sampleTool],
+        subagents: [
+          {
+            name: "sports-info",
+            description:
+              "A specialized sports agent that can get soccer scores and check match day weather.",
+            runnable: innerDeepAgent,
+          } satisfies CompiledSubAgent,
+        ],
+      });
+      assertAllDeepAgentQualities(parentAgent);
+
+      const result = await parentAgent.invoke(
+        {
+          messages: [
+            new HumanMessage(
+              "What are the latest scores for Manchester United?",
+            ),
+          ],
+        },
+        { recursionLimit: 100 },
+      );
+
+      const agentMessages = result.messages.filter(AIMessage.isInstance);
+      const toolCalls = agentMessages.flatMap((msg) => msg.tool_calls || []);
+
+      expect(
+        toolCalls.some(
+          (tc) =>
+            tc.name === "task" && tc.args?.subagent_type === "sports-info",
+        ),
+      ).toBe(true);
+    },
+  );
+
   // Note: response_format with ToolStrategy is not yet available in LangChain TS v1
   // Skipping test_response_format_tool_strategy for now
 });