560 lines
42 KiB
Markdown
560 lines
42 KiB
Markdown
# 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
|