@librechat/agents 2.4.322 → 3.0.0-rc10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (279) hide show
  1. package/dist/cjs/agents/AgentContext.cjs +218 -0
  2. package/dist/cjs/agents/AgentContext.cjs.map +1 -0
  3. package/dist/cjs/common/enum.cjs +15 -5
  4. package/dist/cjs/common/enum.cjs.map +1 -1
  5. package/dist/cjs/events.cjs +10 -6
  6. package/dist/cjs/events.cjs.map +1 -1
  7. package/dist/cjs/graphs/Graph.cjs +309 -213
  8. package/dist/cjs/graphs/Graph.cjs.map +1 -1
  9. package/dist/cjs/graphs/MultiAgentGraph.cjs +507 -0
  10. package/dist/cjs/graphs/MultiAgentGraph.cjs.map +1 -0
  11. package/dist/cjs/llm/anthropic/index.cjs +54 -9
  12. package/dist/cjs/llm/anthropic/index.cjs.map +1 -1
  13. package/dist/cjs/llm/anthropic/types.cjs.map +1 -1
  14. package/dist/cjs/llm/anthropic/utils/message_inputs.cjs +52 -6
  15. package/dist/cjs/llm/anthropic/utils/message_inputs.cjs.map +1 -1
  16. package/dist/cjs/llm/anthropic/utils/message_outputs.cjs +22 -2
  17. package/dist/cjs/llm/anthropic/utils/message_outputs.cjs.map +1 -1
  18. package/dist/cjs/llm/anthropic/utils/tools.cjs +29 -0
  19. package/dist/cjs/llm/anthropic/utils/tools.cjs.map +1 -0
  20. package/dist/cjs/llm/google/index.cjs +144 -0
  21. package/dist/cjs/llm/google/index.cjs.map +1 -0
  22. package/dist/cjs/llm/google/utils/common.cjs +477 -0
  23. package/dist/cjs/llm/google/utils/common.cjs.map +1 -0
  24. package/dist/cjs/llm/ollama/index.cjs +67 -0
  25. package/dist/cjs/llm/ollama/index.cjs.map +1 -0
  26. package/dist/cjs/llm/ollama/utils.cjs +158 -0
  27. package/dist/cjs/llm/ollama/utils.cjs.map +1 -0
  28. package/dist/cjs/llm/openai/index.cjs +422 -3
  29. package/dist/cjs/llm/openai/index.cjs.map +1 -1
  30. package/dist/cjs/llm/openai/utils/index.cjs +672 -0
  31. package/dist/cjs/llm/openai/utils/index.cjs.map +1 -0
  32. package/dist/cjs/llm/providers.cjs +15 -15
  33. package/dist/cjs/llm/providers.cjs.map +1 -1
  34. package/dist/cjs/llm/text.cjs +14 -3
  35. package/dist/cjs/llm/text.cjs.map +1 -1
  36. package/dist/cjs/llm/vertexai/index.cjs +330 -0
  37. package/dist/cjs/llm/vertexai/index.cjs.map +1 -0
  38. package/dist/cjs/main.cjs +11 -0
  39. package/dist/cjs/main.cjs.map +1 -1
  40. package/dist/cjs/run.cjs +137 -85
  41. package/dist/cjs/run.cjs.map +1 -1
  42. package/dist/cjs/stream.cjs +86 -52
  43. package/dist/cjs/stream.cjs.map +1 -1
  44. package/dist/cjs/tools/ToolNode.cjs +10 -4
  45. package/dist/cjs/tools/ToolNode.cjs.map +1 -1
  46. package/dist/cjs/tools/handlers.cjs +119 -13
  47. package/dist/cjs/tools/handlers.cjs.map +1 -1
  48. package/dist/cjs/tools/search/anthropic.cjs +40 -0
  49. package/dist/cjs/tools/search/anthropic.cjs.map +1 -0
  50. package/dist/cjs/tools/search/firecrawl.cjs +55 -9
  51. package/dist/cjs/tools/search/firecrawl.cjs.map +1 -1
  52. package/dist/cjs/tools/search/format.cjs +6 -6
  53. package/dist/cjs/tools/search/format.cjs.map +1 -1
  54. package/dist/cjs/tools/search/rerankers.cjs +7 -29
  55. package/dist/cjs/tools/search/rerankers.cjs.map +1 -1
  56. package/dist/cjs/tools/search/search.cjs +86 -16
  57. package/dist/cjs/tools/search/search.cjs.map +1 -1
  58. package/dist/cjs/tools/search/tool.cjs +4 -2
  59. package/dist/cjs/tools/search/tool.cjs.map +1 -1
  60. package/dist/cjs/tools/search/utils.cjs +1 -1
  61. package/dist/cjs/tools/search/utils.cjs.map +1 -1
  62. package/dist/cjs/utils/events.cjs +31 -0
  63. package/dist/cjs/utils/events.cjs.map +1 -0
  64. package/dist/cjs/utils/title.cjs +57 -21
  65. package/dist/cjs/utils/title.cjs.map +1 -1
  66. package/dist/cjs/utils/tokens.cjs +54 -7
  67. package/dist/cjs/utils/tokens.cjs.map +1 -1
  68. package/dist/esm/agents/AgentContext.mjs +216 -0
  69. package/dist/esm/agents/AgentContext.mjs.map +1 -0
  70. package/dist/esm/common/enum.mjs +16 -6
  71. package/dist/esm/common/enum.mjs.map +1 -1
  72. package/dist/esm/events.mjs +10 -6
  73. package/dist/esm/events.mjs.map +1 -1
  74. package/dist/esm/graphs/Graph.mjs +311 -215
  75. package/dist/esm/graphs/Graph.mjs.map +1 -1
  76. package/dist/esm/graphs/MultiAgentGraph.mjs +505 -0
  77. package/dist/esm/graphs/MultiAgentGraph.mjs.map +1 -0
  78. package/dist/esm/llm/anthropic/index.mjs +54 -9
  79. package/dist/esm/llm/anthropic/index.mjs.map +1 -1
  80. package/dist/esm/llm/anthropic/types.mjs.map +1 -1
  81. package/dist/esm/llm/anthropic/utils/message_inputs.mjs +52 -6
  82. package/dist/esm/llm/anthropic/utils/message_inputs.mjs.map +1 -1
  83. package/dist/esm/llm/anthropic/utils/message_outputs.mjs +22 -2
  84. package/dist/esm/llm/anthropic/utils/message_outputs.mjs.map +1 -1
  85. package/dist/esm/llm/anthropic/utils/tools.mjs +27 -0
  86. package/dist/esm/llm/anthropic/utils/tools.mjs.map +1 -0
  87. package/dist/esm/llm/google/index.mjs +142 -0
  88. package/dist/esm/llm/google/index.mjs.map +1 -0
  89. package/dist/esm/llm/google/utils/common.mjs +471 -0
  90. package/dist/esm/llm/google/utils/common.mjs.map +1 -0
  91. package/dist/esm/llm/ollama/index.mjs +65 -0
  92. package/dist/esm/llm/ollama/index.mjs.map +1 -0
  93. package/dist/esm/llm/ollama/utils.mjs +155 -0
  94. package/dist/esm/llm/ollama/utils.mjs.map +1 -0
  95. package/dist/esm/llm/openai/index.mjs +421 -4
  96. package/dist/esm/llm/openai/index.mjs.map +1 -1
  97. package/dist/esm/llm/openai/utils/index.mjs +666 -0
  98. package/dist/esm/llm/openai/utils/index.mjs.map +1 -0
  99. package/dist/esm/llm/providers.mjs +5 -5
  100. package/dist/esm/llm/providers.mjs.map +1 -1
  101. package/dist/esm/llm/text.mjs +14 -3
  102. package/dist/esm/llm/text.mjs.map +1 -1
  103. package/dist/esm/llm/vertexai/index.mjs +328 -0
  104. package/dist/esm/llm/vertexai/index.mjs.map +1 -0
  105. package/dist/esm/main.mjs +6 -5
  106. package/dist/esm/main.mjs.map +1 -1
  107. package/dist/esm/run.mjs +138 -87
  108. package/dist/esm/run.mjs.map +1 -1
  109. package/dist/esm/stream.mjs +88 -55
  110. package/dist/esm/stream.mjs.map +1 -1
  111. package/dist/esm/tools/ToolNode.mjs +10 -4
  112. package/dist/esm/tools/ToolNode.mjs.map +1 -1
  113. package/dist/esm/tools/handlers.mjs +119 -15
  114. package/dist/esm/tools/handlers.mjs.map +1 -1
  115. package/dist/esm/tools/search/anthropic.mjs +37 -0
  116. package/dist/esm/tools/search/anthropic.mjs.map +1 -0
  117. package/dist/esm/tools/search/firecrawl.mjs +55 -9
  118. package/dist/esm/tools/search/firecrawl.mjs.map +1 -1
  119. package/dist/esm/tools/search/format.mjs +7 -7
  120. package/dist/esm/tools/search/format.mjs.map +1 -1
  121. package/dist/esm/tools/search/rerankers.mjs +7 -29
  122. package/dist/esm/tools/search/rerankers.mjs.map +1 -1
  123. package/dist/esm/tools/search/search.mjs +86 -16
  124. package/dist/esm/tools/search/search.mjs.map +1 -1
  125. package/dist/esm/tools/search/tool.mjs +4 -2
  126. package/dist/esm/tools/search/tool.mjs.map +1 -1
  127. package/dist/esm/tools/search/utils.mjs +1 -1
  128. package/dist/esm/tools/search/utils.mjs.map +1 -1
  129. package/dist/esm/utils/events.mjs +29 -0
  130. package/dist/esm/utils/events.mjs.map +1 -0
  131. package/dist/esm/utils/title.mjs +57 -22
  132. package/dist/esm/utils/title.mjs.map +1 -1
  133. package/dist/esm/utils/tokens.mjs +54 -8
  134. package/dist/esm/utils/tokens.mjs.map +1 -1
  135. package/dist/types/agents/AgentContext.d.ts +91 -0
  136. package/dist/types/common/enum.d.ts +17 -7
  137. package/dist/types/events.d.ts +5 -4
  138. package/dist/types/graphs/Graph.d.ts +64 -67
  139. package/dist/types/graphs/MultiAgentGraph.d.ts +47 -0
  140. package/dist/types/graphs/index.d.ts +1 -0
  141. package/dist/types/llm/anthropic/index.d.ts +11 -0
  142. package/dist/types/llm/anthropic/types.d.ts +9 -3
  143. package/dist/types/llm/anthropic/utils/message_inputs.d.ts +1 -1
  144. package/dist/types/llm/anthropic/utils/output_parsers.d.ts +4 -4
  145. package/dist/types/llm/anthropic/utils/tools.d.ts +3 -0
  146. package/dist/types/llm/google/index.d.ts +13 -0
  147. package/dist/types/llm/google/types.d.ts +32 -0
  148. package/dist/types/llm/google/utils/common.d.ts +19 -0
  149. package/dist/types/llm/google/utils/tools.d.ts +10 -0
  150. package/dist/types/llm/google/utils/zod_to_genai_parameters.d.ts +14 -0
  151. package/dist/types/llm/ollama/index.d.ts +7 -0
  152. package/dist/types/llm/ollama/utils.d.ts +7 -0
  153. package/dist/types/llm/openai/index.d.ts +82 -3
  154. package/dist/types/llm/openai/types.d.ts +10 -0
  155. package/dist/types/llm/openai/utils/index.d.ts +20 -0
  156. package/dist/types/llm/text.d.ts +1 -1
  157. package/dist/types/llm/vertexai/index.d.ts +293 -0
  158. package/dist/types/messages/reducer.d.ts +9 -0
  159. package/dist/types/run.d.ts +19 -12
  160. package/dist/types/stream.d.ts +10 -3
  161. package/dist/types/tools/CodeExecutor.d.ts +2 -2
  162. package/dist/types/tools/ToolNode.d.ts +1 -1
  163. package/dist/types/tools/handlers.d.ts +17 -4
  164. package/dist/types/tools/search/anthropic.d.ts +16 -0
  165. package/dist/types/tools/search/firecrawl.d.ts +15 -0
  166. package/dist/types/tools/search/rerankers.d.ts +0 -1
  167. package/dist/types/tools/search/types.d.ts +30 -9
  168. package/dist/types/types/graph.d.ts +129 -15
  169. package/dist/types/types/llm.d.ts +25 -10
  170. package/dist/types/types/run.d.ts +50 -8
  171. package/dist/types/types/stream.d.ts +16 -2
  172. package/dist/types/types/tools.d.ts +1 -1
  173. package/dist/types/utils/events.d.ts +6 -0
  174. package/dist/types/utils/title.d.ts +2 -1
  175. package/dist/types/utils/tokens.d.ts +24 -0
  176. package/package.json +41 -17
  177. package/src/agents/AgentContext.ts +315 -0
  178. package/src/common/enum.ts +15 -5
  179. package/src/events.ts +24 -13
  180. package/src/graphs/Graph.ts +495 -313
  181. package/src/graphs/MultiAgentGraph.ts +598 -0
  182. package/src/graphs/index.ts +2 -1
  183. package/src/llm/anthropic/Jacob_Lee_Resume_2023.pdf +0 -0
  184. package/src/llm/anthropic/index.ts +78 -13
  185. package/src/llm/anthropic/llm.spec.ts +491 -115
  186. package/src/llm/anthropic/types.ts +39 -3
  187. package/src/llm/anthropic/utils/message_inputs.ts +67 -11
  188. package/src/llm/anthropic/utils/message_outputs.ts +21 -2
  189. package/src/llm/anthropic/utils/output_parsers.ts +25 -6
  190. package/src/llm/anthropic/utils/tools.ts +29 -0
  191. package/src/llm/google/index.ts +218 -0
  192. package/src/llm/google/types.ts +43 -0
  193. package/src/llm/google/utils/common.ts +646 -0
  194. package/src/llm/google/utils/tools.ts +160 -0
  195. package/src/llm/google/utils/zod_to_genai_parameters.ts +86 -0
  196. package/src/llm/ollama/index.ts +89 -0
  197. package/src/llm/ollama/utils.ts +193 -0
  198. package/src/llm/openai/index.ts +641 -14
  199. package/src/llm/openai/types.ts +24 -0
  200. package/src/llm/openai/utils/index.ts +912 -0
  201. package/src/llm/openai/utils/isReasoningModel.test.ts +90 -0
  202. package/src/llm/providers.ts +10 -9
  203. package/src/llm/text.ts +26 -7
  204. package/src/llm/vertexai/index.ts +360 -0
  205. package/src/messages/reducer.ts +80 -0
  206. package/src/run.ts +196 -116
  207. package/src/scripts/ant_web_search.ts +158 -0
  208. package/src/scripts/args.ts +12 -8
  209. package/src/scripts/cli4.ts +29 -21
  210. package/src/scripts/cli5.ts +29 -21
  211. package/src/scripts/code_exec.ts +54 -23
  212. package/src/scripts/code_exec_files.ts +48 -17
  213. package/src/scripts/code_exec_simple.ts +46 -27
  214. package/src/scripts/handoff-test.ts +135 -0
  215. package/src/scripts/image.ts +52 -20
  216. package/src/scripts/multi-agent-chain.ts +278 -0
  217. package/src/scripts/multi-agent-conditional.ts +220 -0
  218. package/src/scripts/multi-agent-document-review-chain.ts +197 -0
  219. package/src/scripts/multi-agent-hybrid-flow.ts +310 -0
  220. package/src/scripts/multi-agent-parallel.ts +341 -0
  221. package/src/scripts/multi-agent-sequence.ts +212 -0
  222. package/src/scripts/multi-agent-supervisor.ts +362 -0
  223. package/src/scripts/multi-agent-test.ts +186 -0
  224. package/src/scripts/search.ts +1 -9
  225. package/src/scripts/simple.ts +25 -10
  226. package/src/scripts/test-custom-prompt-key.ts +145 -0
  227. package/src/scripts/test-handoff-input.ts +170 -0
  228. package/src/scripts/test-multi-agent-list-handoff.ts +261 -0
  229. package/src/scripts/test-tools-before-handoff.ts +233 -0
  230. package/src/scripts/tools.ts +48 -18
  231. package/src/specs/anthropic.simple.test.ts +150 -34
  232. package/src/specs/azure.simple.test.ts +325 -0
  233. package/src/specs/openai.simple.test.ts +140 -33
  234. package/src/specs/openrouter.simple.test.ts +107 -0
  235. package/src/specs/prune.test.ts +4 -9
  236. package/src/specs/reasoning.test.ts +80 -44
  237. package/src/specs/token-memoization.test.ts +39 -0
  238. package/src/stream.test.ts +94 -0
  239. package/src/stream.ts +143 -61
  240. package/src/tools/ToolNode.ts +21 -7
  241. package/src/tools/handlers.ts +192 -18
  242. package/src/tools/search/anthropic.ts +51 -0
  243. package/src/tools/search/firecrawl.ts +69 -20
  244. package/src/tools/search/format.ts +6 -8
  245. package/src/tools/search/rerankers.ts +7 -40
  246. package/src/tools/search/search.ts +97 -16
  247. package/src/tools/search/tool.ts +5 -2
  248. package/src/tools/search/types.ts +30 -10
  249. package/src/tools/search/utils.ts +1 -1
  250. package/src/types/graph.ts +318 -103
  251. package/src/types/llm.ts +26 -12
  252. package/src/types/run.ts +56 -13
  253. package/src/types/stream.ts +22 -1
  254. package/src/types/tools.ts +16 -10
  255. package/src/utils/events.ts +32 -0
  256. package/src/utils/llmConfig.ts +19 -7
  257. package/src/utils/title.ts +104 -30
  258. package/src/utils/tokens.ts +69 -10
  259. package/dist/types/scripts/abort.d.ts +0 -1
  260. package/dist/types/scripts/args.d.ts +0 -6
  261. package/dist/types/scripts/caching.d.ts +0 -1
  262. package/dist/types/scripts/cli.d.ts +0 -1
  263. package/dist/types/scripts/cli2.d.ts +0 -1
  264. package/dist/types/scripts/cli3.d.ts +0 -1
  265. package/dist/types/scripts/cli4.d.ts +0 -1
  266. package/dist/types/scripts/cli5.d.ts +0 -1
  267. package/dist/types/scripts/code_exec.d.ts +0 -1
  268. package/dist/types/scripts/code_exec_files.d.ts +0 -1
  269. package/dist/types/scripts/code_exec_simple.d.ts +0 -1
  270. package/dist/types/scripts/content.d.ts +0 -1
  271. package/dist/types/scripts/empty_input.d.ts +0 -1
  272. package/dist/types/scripts/image.d.ts +0 -1
  273. package/dist/types/scripts/memory.d.ts +0 -1
  274. package/dist/types/scripts/search.d.ts +0 -1
  275. package/dist/types/scripts/simple.d.ts +0 -1
  276. package/dist/types/scripts/stream.d.ts +0 -1
  277. package/dist/types/scripts/thinking.d.ts +0 -1
  278. package/dist/types/scripts/tools.d.ts +0 -1
  279. package/dist/types/specs/spec.utils.d.ts +0 -1
@@ -0,0 +1,310 @@
1
+ import { config } from 'dotenv';
2
+ config();
3
+
4
+ import { HumanMessage, BaseMessage } from '@langchain/core/messages';
5
+ import { Run } from '@/run';
6
+ import { Providers, GraphEvents, Constants } from '@/common';
7
+ import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
8
+ import { ToolEndHandler, ModelEndHandler } from '@/events';
9
+ import type * as t from '@/types';
10
+
11
+ const conversationHistory: BaseMessage[] = [];
12
+
13
+ /**
14
+ * Example of hybrid multi-agent system combining handoff and sequential patterns
15
+ *
16
+ * Graph structure:
17
+ * START -> primary_agent -> agent_b -> agent_c -> END
18
+ * |
19
+ * └─> standalone_agent -> END
20
+ *
21
+ * Because primary_agent has BOTH handoff and direct edges:
22
+ * - Uses Command-based routing for exclusive execution
23
+ * - The primary agent can either:
24
+ * 1. Handoff to standalone_agent (direct edge to agent_b is cancelled)
25
+ * 2. OR continue to agent_b -> agent_c (if no handoff occurs)
26
+ *
27
+ * This is automatic behavior when an agent has both edge types.
28
+ */
29
+ async function testHybridMultiAgent() {
30
+ console.log('Testing Hybrid Multi-Agent System (Sequential + Handoff)...\n');
31
+
32
+ // Define agents
33
+ const agents: t.AgentInputs[] = [
34
+ {
35
+ agentId: 'primary_agent',
36
+ provider: Providers.OPENAI,
37
+ clientOptions: {
38
+ modelName: 'gpt-4.1-mini',
39
+ apiKey: process.env.OPENAI_API_KEY,
40
+ },
41
+ instructions: `You are the Primary Agent in a hybrid workflow.
42
+
43
+ You have TWO options:
44
+ 1. If the request requires specialized expertise (complex analysis, deep technical knowledge, etc.),
45
+ use the "transfer_to_standalone_agent" tool to hand off to the Standalone Specialist
46
+ 2. If the request is straightforward and can be handled through standard processing,
47
+ just provide your initial response and it will automatically continue to Agent B
48
+
49
+ Be decisive - either handoff immediately or provide your response.
50
+ Start your response with "PRIMARY AGENT:" if you're handling it yourself.`,
51
+ maxContextTokens: 8000,
52
+ },
53
+ {
54
+ agentId: 'standalone_agent',
55
+ provider: Providers.OPENAI,
56
+ clientOptions: {
57
+ modelName: 'gpt-4.1',
58
+ apiKey: process.env.OPENAI_API_KEY,
59
+ },
60
+ instructions: `You are a Standalone Specialist Agent.
61
+ You only receive requests that require specialized expertise.
62
+
63
+ Provide a comprehensive, expert-level response to the request.
64
+ Start your response with "STANDALONE SPECIALIST:"
65
+ End with "Specialized analysis complete."`,
66
+ maxContextTokens: 8000,
67
+ },
68
+ {
69
+ agentId: 'agent_b',
70
+ provider: Providers.OPENAI,
71
+ clientOptions: {
72
+ modelName: 'gpt-4.1',
73
+ apiKey: process.env.OPENAI_API_KEY,
74
+ },
75
+ instructions: `You are Agent B in a sequential workflow.
76
+ You receive requests that the Primary Agent decided to handle through standard processing.
77
+
78
+ Your job is to:
79
+ 1. Build upon the Primary Agent's initial response
80
+ 2. Add additional processing or analysis (keep it brief, 2-3 sentences)
81
+ 3. Prepare the information for final processing by Agent C
82
+
83
+ Start your response with "AGENT B:" and end with "Passing to final processing..."`,
84
+ maxContextTokens: 8000,
85
+ },
86
+ {
87
+ agentId: 'agent_c',
88
+ provider: Providers.OPENAI,
89
+ clientOptions: {
90
+ modelName: 'gpt-4.1',
91
+ apiKey: process.env.OPENAI_API_KEY,
92
+ },
93
+ instructions: `You are Agent C, the final agent in the sequential workflow.
94
+
95
+ Your job is to:
96
+ 1. Review all previous processing from Primary Agent and Agent B
97
+ 2. Provide a final summary or conclusion
98
+ 3. Complete the standard workflow
99
+
100
+ Start your response with "AGENT C:" and end with "Standard workflow complete."`,
101
+ maxContextTokens: 8000,
102
+ },
103
+ ];
104
+
105
+ // Define edges combining handoff and direct patterns
106
+ const edges: t.GraphEdge[] = [
107
+ // Handoff edge: primary can transfer to standalone
108
+ {
109
+ from: 'primary_agent',
110
+ to: 'standalone_agent',
111
+ edgeType: 'handoff',
112
+ description: 'Transfer to standalone specialist for complex requests',
113
+ prompt: 'Specific instructions for the specialist',
114
+ },
115
+ // Direct edge - exclusive with handoffs (automatic when agent has both types)
116
+ {
117
+ from: 'primary_agent',
118
+ to: 'agent_b',
119
+ edgeType: 'direct',
120
+ description: 'Continue to Agent B only if no handoff occurs',
121
+ },
122
+ // Direct edge: agent_b automatically continues to agent_c
123
+ {
124
+ from: 'agent_b',
125
+ to: 'agent_c',
126
+ edgeType: 'direct',
127
+ description: 'Automatic progression from B to C',
128
+ },
129
+ ];
130
+
131
+ try {
132
+ // Test with different queries
133
+ const testQueries = [
134
+ {
135
+ query: 'What is the capital of France?',
136
+ expectedPath: 'sequential',
137
+ description: 'Simple query - should go through sequential flow',
138
+ },
139
+ // {
140
+ // query: 'Design a distributed microservices architecture for a real-time trading platform with sub-millisecond latency requirements',
141
+ // expectedPath: 'handoff',
142
+ // description: 'Complex query - should handoff to specialist',
143
+ // },
144
+ ];
145
+
146
+ const config = {
147
+ configurable: {
148
+ thread_id: 'hybrid-conversation-1',
149
+ },
150
+ streamMode: 'values',
151
+ version: 'v2' as const,
152
+ };
153
+
154
+ for (const test of testQueries) {
155
+ console.log(`\n${'='.repeat(70)}`);
156
+ console.log(`TEST: ${test.description}`);
157
+ console.log(`QUERY: "${test.query}"`);
158
+ console.log(`EXPECTED PATH: ${test.expectedPath}`);
159
+ console.log('='.repeat(70));
160
+
161
+ // Reset state
162
+ conversationHistory.length = 0;
163
+ conversationHistory.push(new HumanMessage(test.query));
164
+
165
+ // Create separate content aggregator for each test
166
+ const { contentParts, aggregateContent } = createContentAggregator();
167
+
168
+ // Track agent progression for this test
169
+ let currentAgent = '';
170
+ let handoffOccurred = false;
171
+
172
+ // Create custom handlers for this test
173
+ const customHandlers = {
174
+ [GraphEvents.TOOL_END]: new ToolEndHandler(),
175
+ [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
176
+ [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
177
+ [GraphEvents.ON_RUN_STEP]: {
178
+ handle: (
179
+ event: GraphEvents.ON_RUN_STEP,
180
+ data: t.StreamEventData
181
+ ): void => {
182
+ const runStepData = data as any;
183
+ if (runStepData?.name) {
184
+ currentAgent = runStepData.name;
185
+ console.log(`\n[${currentAgent}] Processing...`);
186
+ }
187
+ aggregateContent({ event, data: data as t.RunStep });
188
+ },
189
+ },
190
+ [GraphEvents.ON_RUN_STEP_COMPLETED]: {
191
+ handle: (
192
+ event: GraphEvents.ON_RUN_STEP_COMPLETED,
193
+ data: t.StreamEventData
194
+ ): void => {
195
+ const runStepData = data as any;
196
+ if (runStepData?.name) {
197
+ console.log(`✓ ${runStepData.name} completed`);
198
+ }
199
+ aggregateContent({
200
+ event,
201
+ data: data as unknown as { result: t.ToolEndEvent },
202
+ });
203
+ },
204
+ },
205
+ [GraphEvents.ON_MESSAGE_DELTA]: {
206
+ handle: (
207
+ event: GraphEvents.ON_MESSAGE_DELTA,
208
+ data: t.StreamEventData
209
+ ): void => {
210
+ // console.dir(data, { depth: null });
211
+ aggregateContent({ event, data: data as t.MessageDeltaEvent });
212
+ },
213
+ },
214
+ [GraphEvents.TOOL_START]: {
215
+ handle: (
216
+ _event: string,
217
+ data: t.StreamEventData,
218
+ metadata?: Record<string, unknown>
219
+ ): void => {
220
+ const toolData = data as any;
221
+ if (toolData?.name?.startsWith(Constants.LC_TRANSFER_TO_)) {
222
+ const specialist = toolData.name.replace(
223
+ Constants.LC_TRANSFER_TO_,
224
+ ''
225
+ );
226
+ console.log(`\n🔀 Transferring to ${specialist}...`);
227
+ handoffOccurred = true;
228
+ }
229
+ },
230
+ },
231
+ };
232
+
233
+ // Create a new run configuration for each test
234
+ const runConfig: t.RunConfig = {
235
+ runId: `hybrid-multi-agent-${test.expectedPath}-${Date.now()}`,
236
+ graphConfig: {
237
+ type: 'multi-agent',
238
+ agents,
239
+ edges,
240
+ },
241
+ customHandlers,
242
+ returnContent: true,
243
+ };
244
+
245
+ // Create and execute a new run for this test
246
+ const run = await Run.create(runConfig);
247
+
248
+ console.log('\nProcessing request...');
249
+
250
+ // Process with streaming
251
+ const inputs = {
252
+ messages: conversationHistory,
253
+ };
254
+
255
+ const finalContentParts = await run.processStream(inputs, config);
256
+ const finalMessages = run.getRunMessages();
257
+
258
+ if (finalMessages) {
259
+ conversationHistory.push(...finalMessages);
260
+ }
261
+
262
+ // Show path taken
263
+ console.log(`\n${'─'.repeat(70)}`);
264
+ console.log('PATH ANALYSIS:');
265
+ console.log(`- Query type: ${test.expectedPath}`);
266
+ console.log(`- Handoff occurred: ${handoffOccurred ? 'YES' : 'NO'}`);
267
+ console.log(
268
+ `- Sequential path runs: ${handoffOccurred ? 'NO (exclusive routing)' : 'YES'}`
269
+ );
270
+ console.log(
271
+ `- Result: ${
272
+ (test.expectedPath === 'handoff' &&
273
+ handoffOccurred &&
274
+ !test.query.includes('continue')) ||
275
+ (test.expectedPath === 'sequential' && !handoffOccurred)
276
+ ? '✅ CORRECT'
277
+ : '❌ INCORRECT'
278
+ }`
279
+ );
280
+ console.log('─'.repeat(70));
281
+
282
+ // Display the responses
283
+ const aiMessages = conversationHistory.filter(
284
+ (msg) => msg._getType() === 'ai'
285
+ );
286
+ console.log('\n--- Agent Responses ---');
287
+ aiMessages.forEach((msg, index) => {
288
+ console.log(`\nResponse ${index + 1}:`);
289
+ console.log(msg.content);
290
+ });
291
+ }
292
+
293
+ // Final summary
294
+ console.log(`\n${'='.repeat(70)}`);
295
+ console.log('HYBRID WORKFLOW TEST COMPLETE');
296
+ console.log('='.repeat(70));
297
+ console.log('\nThis test demonstrates automatic exclusive routing:');
298
+ console.log('- When an agent has BOTH handoff and direct edges');
299
+ console.log('- It uses Command-based routing for exclusive execution');
300
+ console.log('- Either handoff OR direct edges execute, never both');
301
+ console.log(
302
+ '\nThis prevents duplicate processing in delegation scenarios!'
303
+ );
304
+ } catch (error) {
305
+ console.error('Error in hybrid multi-agent test:', error);
306
+ }
307
+ }
308
+
309
+ // Run the test
310
+ testHybridMultiAgent();
@@ -0,0 +1,341 @@
1
+ import { config } from 'dotenv';
2
+ config();
3
+
4
+ import { HumanMessage, BaseMessage } from '@langchain/core/messages';
5
+ import { Run } from '@/run';
6
+ import { Providers, GraphEvents } from '@/common';
7
+ import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
8
+ import { ToolEndHandler, ModelEndHandler } from '@/events';
9
+ import type * as t from '@/types';
10
+
11
+ const conversationHistory: BaseMessage[] = [];
12
+
13
+ /**
14
+ * Example of parallel multi-agent system with fan-in/fan-out pattern
15
+ *
16
+ * Graph structure:
17
+ * START -> researcher
18
+ * researcher -> [analyst1, analyst2, analyst3] (fan-out)
19
+ * [analyst1, analyst2, analyst3] -> summarizer (fan-in)
20
+ * summarizer -> END
21
+ */
22
+ async function testParallelMultiAgent() {
23
+ console.log('Testing Parallel Multi-Agent System (Fan-in/Fan-out)...\n');
24
+
25
+ // Note: You may see "Run ID not found in run map" errors during parallel execution.
26
+ // This is a known issue with LangGraph's event streaming when nodes run in parallel.
27
+ // The errors can be safely ignored - the parallel execution still works correctly.
28
+
29
+ // Set up content aggregator
30
+ const { contentParts, aggregateContent } = createContentAggregator();
31
+
32
+ // Define specialized agents
33
+ const agents: t.AgentInputs[] = [
34
+ {
35
+ agentId: 'researcher',
36
+ provider: Providers.ANTHROPIC,
37
+ clientOptions: {
38
+ modelName: 'claude-3-5-sonnet-latest',
39
+ apiKey: process.env.ANTHROPIC_API_KEY,
40
+ },
41
+ instructions: `You are a research coordinator in a multi-agent analysis workflow. Your sole job is to:
42
+
43
+ 1. Analyze the incoming request and break it down into exactly 3 distinct research areas
44
+ 2. Create specific, actionable analysis tasks for each specialist team
45
+ 3. Format your output as clear directives (not analysis yourself)
46
+ 4. Keep your response under 200 words - you are NOT doing the analysis, just coordinating it
47
+
48
+ Example format:
49
+ "ANALYSIS COORDINATION:
50
+ Financial Team: [specific financial analysis task]
51
+ Technical Team: [specific technical analysis task]
52
+ Market Team: [specific market analysis task]
53
+
54
+ Proceed with parallel analysis."
55
+
56
+ Do NOT provide any actual analysis - your job is purely coordination and task assignment.`,
57
+ },
58
+ {
59
+ agentId: 'analyst1',
60
+ provider: Providers.ANTHROPIC,
61
+ clientOptions: {
62
+ modelName: 'claude-3-5-sonnet-latest',
63
+ apiKey: process.env.ANTHROPIC_API_KEY,
64
+ },
65
+ instructions: `You are a FINANCIAL AND ECONOMIC ANALYST in a parallel analysis workflow.
66
+
67
+ CRITICAL: You must provide detailed, substantive financial analysis (minimum 300 words). Focus specifically on:
68
+
69
+ • Economic impact metrics (GDP, productivity, employment effects)
70
+ • Monetary policy implications and inflation considerations
71
+ • Investment flows and capital market disruptions
72
+ • Financial sector transformation and banking impacts
73
+ • Government fiscal policy and tax revenue effects
74
+ • International trade and currency implications
75
+ • Risk assessment and financial stability concerns
76
+
77
+ Provide concrete data, projections, and financial reasoning. Never give empty responses, brief acknowledgments, or defer to other analysts. This is your domain expertise - deliver comprehensive financial analysis.
78
+
79
+ Start your response with "FINANCIAL ANALYSIS:" and provide detailed insights.`,
80
+ },
81
+ {
82
+ agentId: 'analyst2',
83
+ provider: Providers.ANTHROPIC,
84
+ clientOptions: {
85
+ modelName: 'claude-3-5-sonnet-latest',
86
+ apiKey: process.env.ANTHROPIC_API_KEY,
87
+ },
88
+ instructions: `You are a TECHNICAL AND IMPLEMENTATION ANALYST in a parallel analysis workflow.
89
+
90
+ CRITICAL: You must provide detailed, substantive technical analysis (minimum 300 words). Focus specifically on:
91
+
92
+ • AI infrastructure requirements and scalability challenges
93
+ • Computing power, data center, and energy demands
94
+ • Network connectivity and bandwidth requirements
95
+ • Technical barriers to widespread AI adoption
96
+ • Implementation timelines and deployment phases
97
+ • Skills gap analysis and workforce technical requirements
98
+ • Security vulnerabilities and technical risk mitigation
99
+ • Integration challenges with existing systems
100
+
101
+ Provide concrete technical assessments, infrastructure projections, and implementation roadmaps. Never give empty responses, brief acknowledgments, or defer to other analysts. This is your technical expertise domain.
102
+
103
+ Start your response with "TECHNICAL ANALYSIS:" and provide detailed technical insights.`,
104
+ },
105
+ {
106
+ agentId: 'analyst3',
107
+ provider: Providers.ANTHROPIC,
108
+ clientOptions: {
109
+ modelName: 'claude-3-5-sonnet-latest',
110
+ apiKey: process.env.ANTHROPIC_API_KEY,
111
+ },
112
+ instructions: `You are a MARKET AND INDUSTRY ANALYST in a parallel analysis workflow.
113
+
114
+ CRITICAL: You must provide detailed, substantive market analysis (minimum 300 words). Focus specifically on:
115
+
116
+ • Industry disruption patterns and transformation timelines
117
+ • Competitive landscape shifts and market consolidation
118
+ • Consumer adoption rates and behavior changes
119
+ • New business models and market opportunities
120
+ • Geographic market variations and regional impacts
121
+ • Regulatory environment and policy implications
122
+ • Market size projections and growth trajectories
123
+ • Sector-specific impacts (healthcare, finance, manufacturing, etc.)
124
+
125
+ Provide concrete market assessments, competitive analysis, and industry projections. Never give empty responses, brief acknowledgments, or defer to other analysts. This is your market expertise domain.
126
+
127
+ Start your response with "MARKET ANALYSIS:" and provide detailed market insights.`,
128
+ },
129
+ {
130
+ agentId: 'summarizer',
131
+ provider: Providers.ANTHROPIC,
132
+ clientOptions: {
133
+ modelName: 'claude-3-5-sonnet-latest',
134
+ apiKey: process.env.ANTHROPIC_API_KEY,
135
+ },
136
+ instructions: `You are the SYNTHESIS AND SUMMARY EXPERT in a multi-agent workflow.
137
+
138
+ Your job is to:
139
+ 1. Receive and analyze the outputs from all three specialist analysts
140
+ 2. Identify key themes, conflicts, and complementary insights across analyses
141
+ 3. Synthesize findings into a coherent, comprehensive executive summary
142
+ 4. Highlight critical interdependencies between financial, technical, and market factors
143
+ 5. Provide integrated conclusions and strategic recommendations
144
+
145
+ Structure your summary as:
146
+ - EXECUTIVE SUMMARY (key findings)
147
+ - INTEGRATED INSIGHTS (how the three analyses connect)
148
+ - CRITICAL INTERDEPENDENCIES (financial-technical-market intersections)
149
+ - STRATEGIC RECOMMENDATIONS (actionable next steps)
150
+ - RISK ASSESSMENT (combined risk factors from all domains)
151
+
152
+ Minimum 400 words. Create value through integration, not just concatenation of the three analyses.`,
153
+ },
154
+ ];
155
+
156
+ // Define direct edges (fan-out and fan-in)
157
+ const edges: t.GraphEdge[] = [
158
+ {
159
+ from: 'researcher',
160
+ to: ['analyst1', 'analyst2', 'analyst3'], // Fan-out to multiple analysts
161
+ description: 'Distribute research to specialist analysts',
162
+ edgeType: 'direct', // Explicitly set as direct for automatic transition (enables parallel execution)
163
+ },
164
+ {
165
+ from: ['analyst1', 'analyst2', 'analyst3'], // Fan-in from multiple sources
166
+ to: 'summarizer',
167
+ description: 'Aggregate analysis results',
168
+ edgeType: 'direct', // Fan-in is also direct
169
+ // Add prompt when all analysts have provided input
170
+ // prompt: (messages, runStartIndex) => {
171
+ // // Check if we have analysis content from all three analysts
172
+ // // Look for the specific headers each analyst uses
173
+ // const aiMessages = messages.filter(
174
+ // (msg, index) => msg.getType() === 'ai' && index >= runStartIndex
175
+ // );
176
+ // const messageContent = aiMessages.map((msg) => msg.content).join('\n');
177
+
178
+ // const hasFinancialAnalysis = messageContent.includes(
179
+ // 'FINANCIAL ANALYSIS:'
180
+ // );
181
+ // const hasTechnicalAnalysis = messageContent.includes(
182
+ // 'TECHNICAL ANALYSIS:'
183
+ // );
184
+ // const hasMarketAnalysis = messageContent.includes('MARKET ANALYSIS:');
185
+
186
+ // console.log(
187
+ // `Checking for analyses - Financial: ${hasFinancialAnalysis}, Technical: ${hasTechnicalAnalysis}, Market: ${hasMarketAnalysis}`
188
+ // );
189
+
190
+ // if (hasFinancialAnalysis && hasTechnicalAnalysis && hasMarketAnalysis) {
191
+ // return 'Based on the comprehensive analyses from all three specialist teams above, please synthesize their insights into a cohesive executive summary. Focus on the key findings, common themes, and strategic implications across the financial, technical, and market perspectives.';
192
+ // }
193
+ // return undefined; // No prompt if we haven't received all analyst inputs
194
+ // },
195
+ prompt:
196
+ 'Based on the comprehensive analyses from all three specialist teams below, please synthesize their insights into a cohesive executive summary. Focus on the key findings, common themes, and strategic implications across the financial, technical, and market perspectives.\n\n{results}',
197
+ },
198
+ ];
199
+
200
+ // Track which agents are active
201
+ const activeAgents = new Set<string>();
202
+
203
+ // Create custom handlers
204
+ const customHandlers = {
205
+ [GraphEvents.TOOL_END]: new ToolEndHandler(),
206
+ [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
207
+ [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
208
+ [GraphEvents.ON_RUN_STEP_COMPLETED]: {
209
+ handle: (
210
+ event: GraphEvents.ON_RUN_STEP_COMPLETED,
211
+ data: t.StreamEventData
212
+ ): void => {
213
+ console.log('====== ON_RUN_STEP_COMPLETED ======');
214
+ const runStepData = data as any;
215
+ if (runStepData?.name) {
216
+ activeAgents.delete(runStepData.name);
217
+ console.log(`[${runStepData.name}] Completed analysis`);
218
+ }
219
+ aggregateContent({
220
+ event,
221
+ data: data as unknown as { result: t.ToolEndEvent },
222
+ });
223
+ },
224
+ },
225
+ [GraphEvents.ON_RUN_STEP]: {
226
+ handle: (
227
+ event: GraphEvents.ON_RUN_STEP,
228
+ data: t.StreamEventData
229
+ ): void => {
230
+ console.log('====== ON_RUN_STEP ======');
231
+ const runStepData = data as any;
232
+ if (runStepData?.name) {
233
+ activeAgents.add(runStepData.name);
234
+ console.log(`[${runStepData.name}] Starting analysis...`);
235
+ }
236
+ aggregateContent({ event, data: data as t.RunStep });
237
+ },
238
+ },
239
+ [GraphEvents.ON_RUN_STEP_DELTA]: {
240
+ handle: (
241
+ event: GraphEvents.ON_RUN_STEP_DELTA,
242
+ data: t.StreamEventData
243
+ ): void => {
244
+ aggregateContent({ event, data: data as t.RunStepDeltaEvent });
245
+ },
246
+ },
247
+ [GraphEvents.ON_MESSAGE_DELTA]: {
248
+ handle: (
249
+ event: GraphEvents.ON_MESSAGE_DELTA,
250
+ data: t.StreamEventData
251
+ ): void => {
252
+ console.log('====== ON_MESSAGE_DELTA ======');
253
+ console.dir(data, { depth: null });
254
+ aggregateContent({ event, data: data as t.MessageDeltaEvent });
255
+ },
256
+ },
257
+ };
258
+
259
+ // Create multi-agent run configuration
260
+ const runConfig: t.RunConfig = {
261
+ runId: `parallel-multi-agent-${Date.now()}`,
262
+ graphConfig: {
263
+ type: 'multi-agent',
264
+ agents,
265
+ edges,
266
+ // Add compile options to help with parallel execution
267
+ compileOptions: {
268
+ // checkpointer: new MemorySaver(), // Uncomment if needed
269
+ },
270
+ },
271
+ customHandlers,
272
+ returnContent: true,
273
+ };
274
+
275
+ try {
276
+ // Create and execute the run
277
+ const run = await Run.create(runConfig);
278
+
279
+ // Debug: Log the graph structure
280
+ console.log('=== DEBUG: Graph Structure ===');
281
+ const graph = (run as any).Graph;
282
+ console.log('Graph exists:', !!graph);
283
+ if (graph) {
284
+ console.log('Graph type:', graph.constructor.name);
285
+ console.log('AgentContexts exists:', !!graph.agentContexts);
286
+ if (graph.agentContexts) {
287
+ console.log('AgentContexts size:', graph.agentContexts.size);
288
+ for (const [agentId, context] of graph.agentContexts) {
289
+ console.log(`\nAgent: ${agentId}`);
290
+ console.log(
291
+ `Tools: ${context.tools?.map((t: any) => t.name || 'unnamed').join(', ') || 'none'}`
292
+ );
293
+ }
294
+ }
295
+ }
296
+ console.log('=== END DEBUG ===\n');
297
+
298
+ const userMessage = `EXECUTE PARALLEL ANALYSIS WORKFLOW:
299
+
300
+ Step 1: Researcher - identify 3 key analysis areas for AI economic impact
301
+ Step 2: IMMEDIATELY send to ALL THREE analysts simultaneously:
302
+ - analyst1 (financial): Provide detailed economic impact analysis
303
+ - analyst2 (technical): Provide detailed technical implementation analysis
304
+ - analyst3 (market): Provide detailed market disruption analysis
305
+ Step 3: Summarizer - compile all three analyses
306
+
307
+ IMPORTANT: Each analyst must produce substantive analysis (200+ words), not just acknowledgments or empty responses. This is a multi-agent workflow test requiring actual parallel execution.`;
308
+ conversationHistory.push(new HumanMessage(userMessage));
309
+
310
+ console.log('Invoking parallel multi-agent graph...\n');
311
+
312
+ const config = {
313
+ configurable: {
314
+ thread_id: 'parallel-conversation-1',
315
+ },
316
+ streamMode: 'values',
317
+ version: 'v2' as const,
318
+ };
319
+
320
+ // Process with streaming
321
+ const inputs = {
322
+ messages: conversationHistory,
323
+ };
324
+
325
+ const finalContentParts = await run.processStream(inputs, config);
326
+ const finalMessages = run.getRunMessages();
327
+
328
+ if (finalMessages) {
329
+ conversationHistory.push(...finalMessages);
330
+ }
331
+
332
+ console.log('\n\nActive agents during execution:', activeAgents.size);
333
+ console.log('Final content parts:', contentParts.length, 'parts');
334
+ console.dir(contentParts, { depth: null });
335
+ } catch (error) {
336
+ console.error('Error in parallel multi-agent test:', error);
337
+ }
338
+ }
339
+
340
+ // Run the test
341
+ testParallelMultiAgent();