deepagents 0.0.2 → 1.0.0-beta.2

package/README.md

@@ -1,4 +1,4 @@
-# 🧠🤖Deep Agents
+# 🧠🤖 Deep Agents
 
 Using an LLM to call tools in a loop is the simplest form of an agent. This architecture, however, can yield agents that are "shallow" and fail to plan and act over longer, more complex tasks. Applications like "Deep Research", "Manus", and "Claude Code" have gotten around this limitation by implementing a combination of four things: a planning tool, sub agents, access to a file system, and a detailed prompt.
 
@@ -10,7 +10,48 @@ Using an LLM to call tools in a loop is the simplest form of an agent. This arch
 ## Installation
 
 ```bash
-yarn add deepagents
+npm install deepagents
+```
+
+## Usage
+
+You can find a full example for how to use this agent in [research-agent.ts](/examples/research/research-agent.ts):
+
+```ts
+const agent = createDeepAgent({
+  model: new ChatAnthropic({
+    model: "claude-3-5-sonnet-20240620",
+    temperature: 0,
+  }),
+  tools: [internetSearch],
+  instructions: researchInstructions,
+  subagents: [critiqueSubAgent, researchSubAgent],
+});
+
+// Invoke the agent
+const result = await agent.invoke({
+    messages: [{ role: "user", content: "what is langgraph?" }],
+}, { recursionLimit: 1000 });
+
+console.log("🎉 Finished!")
+console.log(`\n\nAgent ToDo List:\n${result.todos.map((todo) => ` - ${todo.content} (${todo.status})`).join("\n")}`);
+console.log(`\n\nAgent Files:\n${Object.entries(result.files).map(([key, value]) => ` - ${key}: ${value}`).join("\n")}`);
+```
+
+Which will return:
+
+```
+🎉 Finished!
+
+Agent ToDo List:
+ - Research LangGraph using the research-agent (completed)
+ - Write a comprehensive report on LangGraph (completed)
+ - Review and critique the report using the critique-agent (completed)
+ - Make necessary revisions to the report (completed)
+
+Agent Files:
+ - /question.txt: What is LangGraph?
+ - /final_report.md: # What is LangGraph? ...
 ```
 
 ## Learn more

package/dist/index.d.ts

@@ -1,13 +1,195 @@
+import * as langchain0 from "langchain";
+import { AgentMiddleware, AgentMiddleware as AgentMiddleware$1, InterruptOnConfig, ReactAgent, StructuredTool } from "langchain";
+import { AnnotationRoot } from "@langchain/langgraph";
+import { z } from "zod/v3";
+import * as _langchain_langgraph_zod0 from "@langchain/langgraph/zod";
+import { StructuredTool as StructuredTool$1 } from "@langchain/core/tools";
+import { LanguageModelLike } from "@langchain/core/language_models/base";
+import { BaseCheckpointSaver, BaseStore } from "@langchain/langgraph-checkpoint";
+import * as _langchain_core_utils_types0 from "@langchain/core/utils/types";
+import { InteropZodObject } from "@langchain/core/utils/types";
+
+//#region src/middleware/fs.d.ts
 /**
- * Deep Agents TypeScript Implementation
+ * Zod v3 schema for FileData
+ */
+declare const FileDataSchema: z.ZodObject<{
+  content: z.ZodArray<z.ZodString, "many">;
+  created_at: z.ZodString;
+  modified_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+  content: string[];
+  created_at: string;
+  modified_at: string;
+}, {
+  content: string[];
+  created_at: string;
+  modified_at: string;
+}>;
+type FileData = z.infer<typeof FileDataSchema>;
+/**
+ * Options for creating filesystem middleware.
+ */
+interface FilesystemMiddlewareOptions {
+  /** Whether to enable longterm memory support */
+  longTermMemory?: boolean;
+  /** Optional custom system prompt override */
+  systemPrompt?: string | null;
+  /** Optional custom tool descriptions override */
+  customToolDescriptions?: Record<string, string> | null;
+  /** Optional token limit before evicting a tool result to the filesystem (default: 20000 tokens, ~80KB) */
+  toolTokenLimitBeforeEvict?: number | null;
+}
+/**
+ * Create filesystem middleware with all tools and features.
+ */
+declare function createFilesystemMiddleware(options?: FilesystemMiddlewareOptions): langchain0.AgentMiddleware<z.ZodObject<{
+  files: _langchain_langgraph_zod0.ReducedZodChannel<z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+    content: z.ZodArray<z.ZodString, "many">;
+    created_at: z.ZodString;
+    modified_at: z.ZodString;
+  }, "strip", z.ZodTypeAny, {
+    content: string[];
+    created_at: string;
+    modified_at: string;
+  }, {
+    content: string[];
+    created_at: string;
+    modified_at: string;
+  }>>>, _langchain_core_utils_types0.InteropZodType<Record<string, {
+    content: string[];
+    created_at: string;
+    modified_at: string;
+  } | null>>>;
+}, "strip", z.ZodTypeAny, {
+  files: Record<string, {
+    content: string[];
+    created_at: string;
+    modified_at: string;
+  }>;
+}, {
+  files?: Record<string, {
+    content: string[];
+    created_at: string;
+    modified_at: string;
+  }> | undefined;
+}>, undefined, any>;
+//#endregion
+//#region src/middleware/subagents.d.ts
+/**
+ * Type definitions for subagents
+ */
+interface SubAgent {
+  /** The name of the agent */
+  name: string;
+  /** The description of the agent */
+  description: string;
+  /** The system prompt to use for the agent */
+  systemPrompt: string;
+  /** The tools to use for the agent (tool instances, not names). Defaults to defaultTools */
+  tools?: StructuredTool[];
+  /** The model for the agent. Defaults to default_model */
+  model?: LanguageModelLike | string;
+  /** Additional middleware to append after default_middleware */
+  middleware?: AgentMiddleware$1[];
+  /** The tool configs to use for the agent */
+  interruptOn?: Record<string, boolean | InterruptOnConfig>;
+}
+/**
+ * Options for creating subagent middleware
+ */
+interface SubAgentMiddlewareOptions {
+  /** The model to use for subagents */
+  defaultModel: LanguageModelLike | string;
+  /** The tools to use for the default general-purpose subagent */
+  defaultTools?: StructuredTool[];
+  /** Default middleware to apply to all subagents */
+  defaultMiddleware?: AgentMiddleware$1[] | null;
+  /** The tool configs for the default general-purpose subagent */
+  defaultInterruptOn?: Record<string, boolean | InterruptOnConfig> | null;
+  /** A list of additional subagents to provide to the agent */
+  subagents?: Array<SubAgent>;
+  /** Full system prompt override */
+  systemPrompt?: string | null;
+  /** Whether to include the general-purpose agent */
+  generalPurposeAgent?: boolean;
+  /** Custom description for the task tool */
+  taskDescription?: string | null;
+}
+/**
+ * Create subagent middleware with task tool
+ */
+declare function createSubAgentMiddleware(options: SubAgentMiddlewareOptions): AgentMiddleware$1;
+//#endregion
+//#region src/middleware/patch_tool_calls.d.ts
+/**
+ * Create middleware that patches dangling tool calls in the messages history.
+ *
+ * When an AI message contains tool_calls but subsequent messages don't include
+ * the corresponding ToolMessage responses, this middleware adds synthetic
+ * ToolMessages saying the tool call was cancelled.
+ *
+ * @returns AgentMiddleware that patches dangling tool calls
+ *
+ * @example
+ * ```typescript
+ * import { createAgent } from "langchain";
+ * import { createPatchToolCallsMiddleware } from "./middleware/patch_tool_calls";
+ *
+ * const agent = createAgent({
+ *   model: "claude-sonnet-4-5-20250929",
+ *   middleware: [createPatchToolCallsMiddleware()],
+ * });
+ * ```
+ */
+declare function createPatchToolCallsMiddleware(): AgentMiddleware;
+//#endregion
+//#region src/agent.d.ts
+/**
+ * Configuration parameters for creating a Deep Agent
+ * Matches Python's create_deep_agent parameters
+ */
+interface CreateDeepAgentParams<ContextSchema extends AnnotationRoot<any> | InteropZodObject = AnnotationRoot<any>> {
+  /** The model to use (model name string or LanguageModelLike instance). Defaults to claude-sonnet-4-5-20250929 */
+  model?: LanguageModelLike | string;
+  /** Tools the agent should have access to */
+  tools?: StructuredTool$1[];
+  /** Custom system prompt for the agent. This will be combined with the base agent prompt */
+  systemPrompt?: string;
+  /** Custom middleware to apply after standard middleware */
+  middleware?: AgentMiddleware[];
+  /** List of subagent specifications for task delegation */
+  subagents?: SubAgent[];
+  /** Structured output response format for the agent */
+  responseFormat?: any;
+  /** Optional schema for context (not persisted between invocations) */
+  contextSchema?: ContextSchema;
+  /** Optional checkpointer for persisting agent state between runs */
+  checkpointer?: BaseCheckpointSaver | boolean;
+  /** Optional store for persisting longterm memories */
+  store?: BaseStore;
+  /** Whether to use longterm memory - requires a store to be provided */
+  useLongtermMemory?: boolean;
+  /** Optional interrupt configuration mapping tool names to interrupt configs */
+  interruptOn?: Record<string, boolean | InterruptOnConfig>;
+  /** The name of the agent */
+  name?: string;
+}
+/**
+ * Create a Deep Agent with middleware-based architecture.
+ *
+ * Matches Python's create_deep_agent function, using middleware for all features:
+ * - Todo management (todoListMiddleware)
+ * - Filesystem tools (createFilesystemMiddleware)
+ * - Subagent delegation (createSubAgentMiddleware)
+ * - Conversation summarization (summarizationMiddleware)
+ * - Prompt caching (anthropicPromptCachingMiddleware)
+ * - Tool call patching (createPatchToolCallsMiddleware)
+ * - Human-in-the-loop (humanInTheLoopMiddleware) - optional
  *
- * A TypeScript port of the Python Deep Agents library for building controllable AI agents with LangGraph.
- * This implementation maintains 1:1 compatibility with the Python version.
+ * @param params Configuration parameters for the agent
+ * @returns ReactAgent instance ready for invocation
  */
-export { createDeepAgent } from "./graph.js";
-export { getDefaultModel } from "./model.js";
-export { createTaskTool } from "./subAgent.js";
-export { writeTodos, readFile, writeFile, editFile, ls } from "./tools.js";
-export { DeepAgentState, fileReducer } from "./state.js";
-export { WRITE_TODOS_DESCRIPTION, TASK_DESCRIPTION_PREFIX, TASK_DESCRIPTION_SUFFIX, EDIT_DESCRIPTION, TOOL_DESCRIPTION, } from "./prompts.js";
-export type { SubAgent, Todo, DeepAgentStateType, CreateDeepAgentParams, CreateTaskToolParams, TodoStatus, } from "./types.js";
+declare function createDeepAgent<ContextSchema extends AnnotationRoot<any> | InteropZodObject = AnnotationRoot<any>>(params?: CreateDeepAgentParams<ContextSchema>): ReactAgent<any, any, ContextSchema, any>;
+//#endregion
+export { type CreateDeepAgentParams, type FileData, createFilesystemMiddleware as FilesystemMiddleware, createFilesystemMiddleware, type FilesystemMiddlewareOptions, type SubAgent, type SubAgentMiddlewareOptions, createDeepAgent, createPatchToolCallsMiddleware, createSubAgentMiddleware };