Entry Points
| Entry | Route | Description |
|---|---|---|
| Web frontend | POST /api/agent/invoke | Next.js API Route, proxied to Python backend |
| Python API | POST /api/agent/invoke | FastAPI route, directly calls AgentService |
| Resume (HITL) | POST /api/agent/resume | Resume execution after user approval |
How It Works (High-level)
- Request Reception — Next.js API validates identity, checks credit balance, loads LLM and tool configuration, asynchronously saves user message, forwards to Python backend
- Context Assembly —
_init_context()sequentially loads tools (MCP + OAuth + Built-in), initializes LLM, retrieves Memory/Profile, activates Skills, builds System Prompt, caches tocontext_cache - Agent Creation — Creates a LangGraph graph via DeepAgents, assembling LLM, tools, middleware pipeline, Checkpointer, and HITL interrupt configuration
- Message Construction — Frontend chat_history is converted to LangChain message types (max 30), with current user message appended
- Streaming Execution — Enters
_astream_events()core loop; framework events are converted to SSE messages and streamed - Completion — Sends
CompleteMessage; Checkpointer automatically saves state
Context Assembly
After context assembly completes, it is cached in_context_cache[session_id] for reuse during HITL resume().
Context Details
System Prompt assembly, Token management & optimization strategies
System Prompt
System prompt — CORE, SOUL, TOOLS, WORKFLOW, MEMORY, dynamic injection
Event Streaming
_astream_events() listens to DeepAgents framework internal events and converts them to standard SSE messages for the frontend:
SSE Event Types
| SSE Event | Trigger Timing | Key Fields |
|---|---|---|
text | LLM outputs each token | content, role |
tool_call | LLM decides to call a tool | tool_name, parameters, requires_approval |
tool_call_result | Tool execution complete | tool_name, result, is_error |
complete | Agent execution finished | content, summary |
error | Exception occurred | error, error_code, details |
token_usage | After LLM call ends | prompt_tokens, completion_tokens |
Messages
Learn about the complete message flow, state management, and persistence
Tool Execution
Execution Decision
Approval decisions are based on Auto-Run mode (Run Everything / Use Allowlist / Ask Everytime). Tool Call IDs are matched via a FIFO queue, stored grouped by tool name; enqueued duringon_chat_model_end, dequeued during on_tool_end.
HITL Interrupt & Recovery
When a tool requires approval, the Agent Loop is suspended and state is persisted via Checkpointer. Recovery flow: Rejected tools have a SystemMessage appended, explicitly telling the Agent not to retry.HITL Details
Complete description of Auto-Run modes, approval UI, and interrupt recovery mechanism
Frontend Processing
The frontendhandleStreamMessage() consumes the SSE stream, routing events to corresponding state management:
Event Persistence
RealtimeEventSaver batch-persists real-time events:
| Configuration | Value |
|---|---|
| Batch size | 3 events |
| Batch interval | 100ms |
| Retry strategy | Exponential backoff, max 3 retries |
| Fallback | LocalStorage backup |
Error Handling
Backend Errors
| Error Type | Detection Condition | User Message |
|---|---|---|
| Input length exceeded | Range of input length / InvalidParameter | Suggest shortening input |
| Context window overflow | context length / token limit | Suggest starting a new session |
| General exception | All other Exceptions | Includes traceback details |
ErrorMessage SSE events, containing error_code and details.
Frontend Errors
| HTTP Status Code | Meaning | Handling |
|---|---|---|
| 401 | Unauthorized | Redirect to login |
| 403 | Insufficient credits | Toast notification |
| 503 | Backend not started | Connection error message |
| 504 | Request timeout | Timeout message |
Timeouts
| Timeout Item | Default | Description |
|---|---|---|
| Agent max execution time | 7200s (2h) | FastAPI single call limit |
| MCP server | 1800s (30min) | Connection timeout per MCP server |
| HITL tool approval | Configurable | Independently set per tool |
| LangGraph recursion limit | 999 | Maximum iteration count for Agent loop |
Concurrency & Isolation
- Each Session has independent Checkpointer state (
thread_idisolation) - Context Cache is isolated by
session_id; resume can only recover the corresponding session - Tool execution is serialized (LangGraph guarantees no concurrent tool execution within the same Session)
- User workspaces are fully isolated by
user_id
Where Things Can End Early
- Agent timeout — Exceeds 7200s maximum execution time
- HITL approval timeout — User does not respond within the specified time
- Frontend disconnect — Network interruption or user closes the page
- Credit exhaustion — Pre-call check fails
- Model error — Context window overflow or API exception