# 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