How rupeshksingh/deepagents works
Project Type and Purpose
• This is an open-source Python library/package (“deepagents”) that provides a framework for building “deep” LLM-based agents.
• It wraps LangGraph and LangChain, offers built-in planning, file-system simulation, subagent orchestration, and human-in-the-loop tooling.
• It also includes an optional REST API layer (in the api/ folder), CLI scripts (main.py, react_agent.py), example usage, and unit tests.
Top-Level Components
• Library Core (src/deepagents/):
– graph.py: constructs the LangGraph graph for the agent.
– middleware.py: registers planning, filesystem, subagent middleware.
– model.py: creates or configures the LangChain model.
– prompts.py: defines the default detailed system prompt.
– state.py & types.py: state schema and type definitions for the graph.
– tools.py: built-in tools (todos, virtual FS operations).
– logging/ & logging_utils.py: instrumentation and debug logging.
• API Layer (api/):
– router.py: FastAPI endpoints to invoke agents via HTTP.
– models.py: Pydantic schemas for requests/responses.
– store.py: in-memory or persistent storage of agent sessions.
– utils.py: common helpers.
• Entry Points:
– main.py & react_agent.py: sample scripts demonstrating how to instantiate and invoke agents.
– tool_utils.py & tools.py at top level: helper wrappers and example external tools.
• Examples (examples/):
– research_agent.py: a full “deep research” agent using the library + TavilyClient.
– requirements, sample LangGraph JSON.
• Tests (test_agent/):
– unit tests for agent invocation, streaming, memory, tool usage.
External Dependencies and Services
• LangGraph: orchestrates the agent as a graph of actions and state transitions.
• LangChain: provides chat models and tool abstractions.
• TavilyClient (example): an external search API for demos.
• FastAPI (in api/): serves HTTP endpoints.
• InMemorySaver (for human-in-the-loop checkpoints).
Relationships and Interactions
1) User Code / Scripts (main.py, examples) call create_deep_agent(...)
2) create_deep_agent (in deepagents/model.py) → builds a LangGraph graph:
• System prompt node (from prompts.py)
• Planning tool middleware (middleware.py)
• Virtual FS middleware (middleware.py → state.py)
• Subagent middleware (middleware.py)
• Tool invocation nodes (tools.py)
3) Graph executes in a loop:
• Each iteration: send context to LLM (LangChain Chat model) → receives action or text
• If it’s a tool call → use internal virtual FS or external tool function
• Update the LangGraph State (state.py) accordingly
4) API layer (api/router.py) exposes HTTP endpoints that:
• Accept JSON payloads (messages, optional files)
• Look up or create an agent session in store.py
• Invoke the agent graph, stream responses back
• Optionally enforce human-in-the-loop via Checkpointer
Architectural Patterns and Principles
• Graph-based orchestration (LangGraph) for modular, composable agent behavior.
• Middleware pattern to inject planning, FS, subagent capabilities.
• Dependency injection: user-supplied tools and subagents are passed into the graph builder.
• Virtual file system: isolate agent file operations in JSON state for safety.
• Human-in-the-loop hook points via tool configurations and checkpoints.
• Clear separation: Core library vs. API vs. examples vs. tests.
Key Technologies & Libraries
• Python 3.10+
• LangGraph (agent graph)
• LangChain (models, tools)
• FastAPI (optional REST API)
• TavilyClient (example external search)
• Pydantic (API models)
• pytest (unit tests)