42 KiB
42 KiB
Walkthrough: AgentCore.jl System Flow
This walkthrough traces the end-to-end flow of the AgentCore.jl system, from startup to task completion, showing how all components work together.
1. System Startup
1.1 Agent Initialization
User Flow: System startup and agent instantiation
┌─────────────────────────────────────────────────────────────────────┐
│ Agent Initialization │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 1. Load Configuration │
│ - Read config from JSON file │
│ - Parse database credentials │
│ - Load tool definitions │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 2. Create Session Repository │
│ - Choose storage backend (JSONL or in-memory) │
│ - Initialize storage directory │
│ - Create session metadata │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 3. Instantiate Agent │
│ - Create AgentState with initial configuration │
│ - Register tools (bash, read, write, edit) │
│ - Set up event subscription system │
└─────────────────────────────────────────────────────────────────────┘
Specification References: SPEC-6.1 (Agent Methods), SPEC-10.1 (Agent Options)
1.2 External Integration Setup
User Flow: Connect to external services (database, LLM, MQTT)
┌─────────────────────────────────────────────────────────────────────┐
│ External Integration │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 1. Database Connections │
│ - Connect to wine database (LibPQ) │
│ - Connect to vector database │
│ - Initialize connection pool │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 2. MQTT Client Setup │
│ - Connect to MQTT broker │
│ - Subscribe to request topic │
│ - Set up message callback │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 3. LLM Service Configuration │
│ - Configure model endpoint │
│ - Set API key │
│ - Configure stream function │
└─────────────────────────────────────────────────────────────────────┘
Specification References: NFR-501 (Deployment Constraints), NFR-502 (Scalability)
2. Conversation Flow
2.1 User Request Handling
User Flow: Customer sends message to AI sommelier
┌─────────────────────────────────────────────────────────────────────┐
│ Customer Interaction │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 1. Receive User Message │
│ - MQTT message arrives │
│ - Parse payload (text, images) │
│ - Generate message ID │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 2. Create User Message Object │
│ - Construct UserMessage with text content │
│ - Add timestamp │
│ - Add to conversation history │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 3. Emit Event │
│ - MessageStartEvent │
│ - MessageEndEvent │
│ - Forward to subscribers (monitoring, logging) │
└─────────────────────────────────────────────────────────────────────┘
Specification References: SPEC-2.2 (UserMessage), SPEC-5.1 (Event Types)
2.2 Agent Processing Loop
User Flow: Agent processes message and prepares response
┌─────────────────────────────────────────────────────────────────────┐
│ Agent Processing │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 1. Transform Messages for LLM │
│ - Convert AgentMessage[] to Message[] │
│ - Filter unsupported message types │
│ - Add conversation history │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 2. Create Context Snapshot │
│ - System prompt │
│ - Message history │
│ - Available tools │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 3. Call LLM Stream Function │
│ - Build API request │
│ - Stream LLM response │
│ - Emit partial messages │
└─────────────────────────────────────────────────────────────────────┘
Specification References: SPEC-2.1 (AgentMessage), SPEC-6.2 (AgentLoop)
2.3 Tool Execution
User Flow: Agent executes tools based on LLM requests
┌─────────────────────────────────────────────────────────────────────┐
│ Tool Execution │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 1. Parse Tool Calls │
│ - Extract tool calls from assistant message │
│ - Validate tool existence │
│ - Prepare arguments │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 2. Execute Tool (Parallel or Sequential) │
│ ├─ Parallel Mode: │
│ │ - Spawn concurrent tasks for each tool │
│ │ - Wait for all to complete │
│ │ - Collect results │
│ │ │
│ └─ Sequential Mode: │
│ - Execute tools one at a time │
│ - Update context after each tool │
│ - Check for early termination │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 3. Emit Tool Events │
│ - ToolExecutionStartEvent │
│ - ToolExecutionUpdateEvent (streaming) │
│ - ToolExecutionEndEvent │
└─────────────────────────────────────────────────────────────────────┘
Specification References: SPEC-1.3 (ToolExecutionMode), SPEC-3.2 (Tool Execution)
3. Tool Implementations
3.1 Bash Tool
User Flow: Execute shell command
┌─────────────────────────────────────────────────────────────────────┐
│ Bash Tool Flow │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 1. Validate Arguments │
│ - Check command is string │
│ - Validate no dangerous flags │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 2. Execute Command │
│ - Spawn subprocess │
│ - Capture stdout/stderr │
│ - Set timeout if configured │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 3. Format Result │
│ - Combine stdout/stderr │
│ - Include exit code │
│ - Truncate if too long (>4096 chars) │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 4. Return Tool Result │
│ - Create AgentToolResult │
│ - Include usage statistics │
│ - Mark as error if exit code != 0 │
└─────────────────────────────────────────────────────────────────────┘
Specification References: SPEC-3.1 (AgentTool), SPEC-7.2 (Tool Errors)
3.2 Wine Database Search Tool
User Flow: Search wine inventory database
┌─────────────────────────────────────────────────────────────────────┐
│ Wine Database Search │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 1. Parse Query │
│ - Extract search criteria │
│ - Parse price range │
│ - Extract wine attributes │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 2. Check Vector Cache │
│ - Get embedding of query │
│ - Search vector DB for similar queries │
│ - Return cached SQL if close match │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 3. Generate SQL Query │
│ - Build WHERE clauses │
│ - Add price filters │
│ - Apply wine type filters │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 4. Execute Database Query │
│ - Connect to database │
│ - Run SQL query │
│ - Fetch results (DataFrame) │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 5. Format Results │
│ - Convert to readable format │
│ - Include wine name, price, vintage │
│ - Limit to top N results (default 10) │
└─────────────────────────────────────────────────────────────────────┘
Specification References: FR-006 (Wine Database Search)
4. Session Persistence
4.1 Saving Conversation History
User Flow: Persist conversation to storage
┌─────────────────────────────────────────────────────────────────────┐
│ Session Persistence │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 1. Create Session Entry │
│ - Generate unique entry ID │
│ - Create MessageEntry with message │
│ - Set timestamp and parent ID │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 2. Write to Storage │
│ - Serialize entry to JSON │
│ - Append to JSONL file │
│ - Update entry index │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 3. Update Session Metadata │
│ - Increment message count │
│ - Update token counts │
│ - Save metadata │
└─────────────────────────────────────────────────────────────────────┘
Specification References: SPEC-4.2 (Session Storage), SPEC-4.3 (SessionStats)
4.2 Session Compaction
User Flow: Reduce context window usage
┌─────────────────────────────────────────────────────────────────────┐
│ Session Compaction │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 1. Determine Compaction Point │
│ - Calculate current token count │
│ - Check if over threshold │
│ - Identify messages to summarize │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 2. Generate Summary │
│ - Extract messages to summarize │
│ - Call LLM with summary prompt │
│ - Get compact summary │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 3. Create Compaction Entry │
│ - Create CompactionEntry │
│ - Store summary and first kept ID │
│ - Record token savings │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 4. Update Session Tree │
│ - Replace old messages with summary │
│ - Update leaf pointer │
│ - Save updated session │
└─────────────────────────────────────────────────────────────────────┘
Specification References: FR-003 (Session Persistence)
5. Event-Driven Architecture
5.1 Event Subscription Flow
User Flow: External systems subscribe to agent events
┌─────────────────────────────────────────────────────────────────────┐
│ Event Subscription │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 1. Subscribe │
│ - Create subscriber channel │
│ - Register listener │
│ - Return unsubscription function │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 2. Event Broadcast │
│ - Event emitted (e.g., MessageEndEvent) │
│ - Broadcast to all subscribers │
│ - Non-blocking delivery │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 3. Event Processing │
│ - Logging service consumes events │
│ - Monitoring service aggregates stats │
│ - Debugging tool displays live stream │
└─────────────────────────────────────────────────────────────────────┘
Specification References: SPEC-5.2 (Event Subscription)
6. Error Handling Flow
6.1 Tool Execution Error
User Flow: Handle tool execution failure
┌─────────────────────────────────────────────────────────────────────┐
│ Error Handling Flow │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 1. Error Caught │
│ - Exception thrown during tool execution │
│ - Error message captured │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 2. Emit Error Event │
│ - ToolExecutionEndEvent with error flag │
│ - Include error message │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 3. Create Error Result │
│ - Create AgentToolResult with error content │
│ - Mark is_error = true │
│ - Include error details │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 4. Send to LLM │
│ - Include error result in tool message │
│ - LLM can decide how to proceed │
└─────────────────────────────────────────────────────────────────────┘
Specification References: SPEC-7.2 (Tool Errors), SPEC-7.1 (Agent Errors)
7. End-to-End Example: Customer Wine Recommendation
7.1 Complete User Journey
User Flow: Customer asks for wine recommendation
┌─────────────────────────────────────────────────────────────────────┐
│ End-to-End: Wine Recommendation │
└─────────────────────────────────────────────────────────────────────┘
1. Customer Message (via MQTT)
"I'm looking for a French red wine under $100"
2. Agent Processing
├─ Parse query
├─ Extract: country=France, price<100, type=red
└─ Determine missing: region, vintage, grape varietal
3. Tool Call: SEARCH_WINE_DATABASE
├─ Query: country=France, type=red, price<100
├─ Execute SQL (with vector cache check)
└─ Return 10 matching wines
4. LLM Response
├─ Analyze results
├─ Select top 3 options
└─ Format recommendation
5. Response to Customer
"I found several French red wines under $100:
- Château Le Grand Montmirail 2020 ($75)
- Domaine de la Mordorée 2019 ($85)
- Louis Latour 2021 ($65)
Which one interests you?"
6. Session Persistence
├─ Save conversation to JSONL
├─ Update token counts
└─ Update session stats
Traceability:
- FR-001: Agent state management throughout
- FR-002: Tool execution for database search
- FR-003: Session persistence after interaction
- FR-004: Event streaming for monitoring
- FR-006: Wine database search functionality
Specification References: SPEC-6.1 (Agent Methods), SPEC-6.2 (AgentLoop), SPEC-3.x (Tool Interface)
8. Performance Characteristics
8.1 Message Processing Timeline
Requirement Reference: NFR-101, KPI-001
Message Processing Timeline (95th percentile):
┌─────────────────────────────────────────────────────────────────────┐
│ 1. Message Receive (MQTT) 50ms │
│ 2. Message Parsing 30ms │
│ 3. LLM API Call 800ms │
│ 4. Tool Execution (if needed) 200ms │
│ 5. Result Formatting 20ms │
│ 6. Response Delivery (MQTT) 100ms │
│ │
│ Total: 1200ms (95th percentile) │
└─────────────────────────────────────────────────────────────────────┘
8.2 Tool Execution Timelines
Requirement Reference: NFR-101
| Tool | 50th Percentile | 95th Percentile | 99th Percentile |
|---|---|---|---|
| Bash | 150ms | 500ms | 1500ms |
| Read | 100ms | 300ms | 800ms |
| Write | 100ms | 400ms | 1000ms |
| Edit | 200ms | 600ms | 1500ms |
| Database Search | 500ms | 1500ms | 3000ms |
Specification References: SPEC-11.1 (Latency Targets)
9. Troubleshooting Guide
9.1 Common Issues
| Issue | Cause | Resolution |
|---|---|---|
| I-001: Agent doesn't respond | Event subscribers not registered | Check subscribe() calls, verify MQTT connection |
| I-002: Tool execution fails | Invalid arguments or tool not found | Validate arguments, check tool registration |
| I-003: Session recovery fails | Storage corrupted or missing | Check JSONL files, verify permissions |
| I-004: High latency | Network or LLM service issues | Check network, verify LLM service health |
| I-005: Context window exceeded | Session too long | Implement compaction, reduce history |
Specification References: SPEC-7.x (Error Codes)
Document Status: v1.0
Last Updated: 2026-07-28
Maintainer: YiemAgent Development Team