diff --git a/ai_system_prompt.md b/.AI_prompt.md similarity index 92% rename from ai_system_prompt.md rename to .AI_prompt.md index 9416427..36fa523 100644 --- a/ai_system_prompt.md +++ b/.AI_prompt.md @@ -80,3 +80,48 @@ Assistant should only respond in JSON format as described below: "action_input": "..." } ``` + + + + + + +read this codebase. I want you to write the following files: +- ./docs/requirements.md +- ./docs/solution-design.md +- ./docs/specification +- ./docs/walkthrough.md +according to /home/ton/docker-apps/sommpanion/ASG_Framework/ASG_Framework.md so I can read and understand this codebase. + + + + + + + + + +echo 'export PATH="$HOME/.juliaup/bin:$PATH"' >> ~/.bashrc + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/requirements.md b/docs/requirements.md new file mode 100644 index 0000000..d9eb2da --- /dev/null +++ b/docs/requirements.md @@ -0,0 +1,190 @@ +# Requirements + +## 1. Business Context & Success Metrics + +### Business Goal + +The **YiemAgent** project is a Julia reimplementation of the Pi Agent Core framework, designed to provide a stateful agent system for LLM interactions in a wine retail store context. This system enables AI agents to interact with customers, search wine databases, and provide personalized wine recommendations based on customer preferences and store inventory. + +### User Stories + +- **US-001**: As a wine store customer, I want to interact with an AI sommelier so that I can get personalized wine recommendations +- **US-002**: As a wine store operator, I want the AI to search our wine database so that I can provide accurate inventory-based recommendations +- **US-003**: As a developer, I want a reusable agent framework so that I can quickly build custom AI agents for different use cases +- **US-004**: As a system administrator, I want session persistence so that I can maintain conversation history across agent restarts + +### KPIs & Targets + +- **KPI-001**: 95% of customer queries receive responses within 3 seconds (measured from query receipt to response delivery) +- **KPI-002**: 99% of wine searches return results from inventory database within 2 seconds +- **KPI-003**: Agent session recovery time < 5 seconds after restart +- **KPI-004**: Conversation context retention accuracy > 95% across session restarts + +## 2. Technical Boundaries + +### In Scope + +- Low-level agent loop with LLM interaction and tool execution +- High-level Agent struct with state management and event streaming +- Session persistence with JSONL-based storage +- Built-in tools: bash execution, file read/write/edit operations +- Conversation history compaction for context window management +- Branch-based conversation navigation +- Event-driven architecture for monitoring and control + +### Out of Scope + +- LLM model hosting or inference (relies on external services) +- Frontend UI components (web interface) +- Database schema design or management +- User authentication and authorization +- Multi-tenant isolation + +### Dependencies + +- Julia 1.9+ runtime +- JSON3 for JSON parsing +- UUIDs for session identification +- Dates for timestamp management +- LibPQ for PostgreSQL database connections +- MQTT client for external communication + +### Deployment Constraints + +- **NFR-501**: System shall be deployed to containerized environment (Docker/Podman) +- **NFR-502**: Agent instances shall support horizontal scaling +- **NFR-503**: Session data shall be persisted in shared storage for failover scenarios + +## 3. Functional Requirements (FR) + +### FR-001: Agent State Management + +The system shall maintain conversation state including message history, active tools, and system prompt. + +- Store and retrieve conversation history +- Support multiple concurrent agent sessions +- Maintain tool state across conversation turns +- Persist agent state to storage backend + +**Traceability**: US-001, US-004 + +### FR-002: Tool Execution + +The system shall execute tools requested by the LLM in response to user queries. + +- Support parallel and sequential tool execution modes +- Handle tool call errors gracefully +- Return tool results to LLM for processing +- Support tool result streaming for long-running operations + +**Traceability**: US-001 + +### FR-003: Session Persistence + +The system shall persist agent sessions to enable recovery after restart. + +- Store session metadata and conversation history in JSONL format +- Support session creation, opening, and deletion +- Enable session branching for experiment tracking +- Support session compaction to reduce storage and context size + +**Traceability**: US-004 + +### FR-004: Event Streaming + +The system shall provide real-time event streaming for monitoring agent activity. + +- Emit lifecycle events (agent start/end, turn start/end, message start/end) +- Emit tool execution events (start, update, end) +- Support event subscription and unsubscription +- Enable event-driven workflows + +**Traceability**: US-001 + +### FR-005: Conversation Management + +The system shall manage conversation flow with support for steering and follow-up messages. + +- Support sequential conversation turns +- Enable message injection after assistant turns (steering) +- Support follow-up messages that run after natural termination +- Clear message queues on agent reset + +**Traceability**: US-001, US-002 + +### FR-006: Wine Database Search + +The system shall provide tools to search wine inventory databases. + +- Execute SQL queries against wine database +- Support vector similarity search for recommendations +- Cache similar queries in vector database +- Handle database connection failures gracefully + +**Traceability**: US-002 + +## 4. Non-Functional Requirements (NFRs) + +### 4.1 Performance & Scalability + +- **NFR-101**: System shall process messages with <500ms latency for 95th percentile +- **NFR-102**: System shall support at least 100 concurrent agent sessions +- **NFR-103**: Tool execution shall complete within 10 seconds for 99% of operations +- **NFR-104**: Session compaction shall reduce token count by at least 50% with minimal context loss + +### 4.2 Availability & Reliability + +- **NFR-201**: Agent sessions shall recover from failures within 5 seconds +- **NFR-202**: System shall maintain conversation continuity across restarts +- **NFR-203**: Message queues shall not lose messages during normal operation +- **NFR-204**: Event streaming shall survive temporary subscriber disconnections + +### 4.3 Privacy & Security + +- **Data Classification**: Commercial wine data, customer preferences +- **Encryption**: TLS 1.3+ for database connections, encrypted session storage +- **Authentication**: Database credential management via environment variables +- **Compliance**: GDPR Article 32 (security of processing) + +### 4.4 Observability & Telemetry + +- **Required Logs**: `session_id`, `message_id`, `event_type`, `timestamp`, `latency_ms`, `tool_name` +- **Critical Metrics**: + - `agent_sessions_active` + - `message_processing_latency_seconds` + - `tool_execution_errors_total` + - `session_recovery_time_seconds` +- **Tracing**: B3 propagation for distributed tracing +- **Alerting**: `tool_execution_error_rate > 5%` triggers PagerDuty +- **Retention**: Logs: 30 days, Metrics: 90 days + +## 5. Acceptance Conditions + +- [ ] **FR-001**: Agent maintains conversation state across multiple turns with correct message ordering +- [ ] **FR-002**: Tools execute correctly with proper error handling and result formatting +- [ ] **FR-003**: Sessions can be persisted and recovered with complete conversation history +- [ ] **FR-004**: All agent lifecycle events are emitted and可 captured by subscribers +- [ ] **FR-005**: Steering messages are injected at correct points in conversation flow +- [ ] **FR-006**: Wine database search returns results within 2 seconds for 95% of queries +- [ ] **NFR-101**: 95% of messages processed within 500ms latency +- [ ] **NFR-201**: Agent sessions recover within 5 seconds after simulated failure + +## 6. Requirements Traceability Matrix + +| Requirement ID | Description | Implementation File | Test File | +|----------------|-------------|---------------------|-----------| +| FR-001 | Agent State Management | `src/agent.jl`, `src/types.jl` | `test/test1.jl` | +| FR-002 | Tool Execution | `src/agent_loop.jl`, `src/tools/` | `test/prompttest_*.jl` | +| FR-003 | Session Persistence | `src/session/` | `test/chatting_with_agent.jl` | +| FR-004 | Event Streaming | `src/agent.jl`, `src/types.jl` | `test/prompttest_*.jl` | +| FR-005 | Conversation Management | `src/agent.jl`, `src/agent_loop.jl` | `test/chatting_with_agent.jl` | +| FR-006 | Wine Database Search | `example/main.jl`, `example/agent_chat_virtualCustomer.jl` | N/A | +| NFR-101 | Performance & Scalability | System-wide | `test/runtests.jl` | +| NFR-201 | Availability & Reliability | `src/session/`, `src/agent.jl` | `test/chatting_with_agent.jl` | + +**Notes**: +- Functional Requirements (FR) define what the system shall do +- Non-Functional Requirements (NFR) define system qualities (performance, availability, security, etc.) +- KPIs are measurable targets that validate whether requirements were met post-deployment +- Each requirement must include a clear requirement ID for traceability +- All acceptance conditions must be verifiable through testing or manual inspection diff --git a/docs/solution-design.md b/docs/solution-design.md new file mode 100644 index 0000000..341c2f7 --- /dev/null +++ b/docs/solution-design.md @@ -0,0 +1,148 @@ +# Solution Design: AgentCore.jl - Julia Agent Framework + +## 1. Problem Decomposition + +This project addresses several interconnected problems in building AI agent systems: + +| Problem | Description | User Impact | +|---------|-------------|-------------| +| **P-001**: Complex state management | AI agents need to maintain conversation history, tool states, and system prompts across multiple turns | Without proper state management, conversations lose context and become inconsistent | +| **P-002**: Tool execution orchestration | LLMs often request multiple tool calls that need to be executed and results returned | Complex coordination required between LLM calls and tool execution | +| **P-003**: Session persistence | Agent sessions need to survive restarts and support branching for experiments | Loss of conversation history requires re-conversation and poor UX | +| **P-004**: Event monitoring | Need to observe agent behavior for debugging and operational visibility | Black-box agents are difficult to debug and monitor in production | +| **P-005**: Context window management | LLMs have limited context windows, requiring history management | Long conversations get truncated, losing important context | + +## 2. Solution Approach + +The solution implements a layered agent framework with clear separation of concerns: + +**Approach**: Implement a low-level agent loop with stateless execution, wrapped in a high-level Agent struct that manages state, queuing, and event streaming. Sessions are persisted to JSONL storage with support for compaction and branching. + +**Key Principles**: +- Separate concerns: low-level loop vs. high-level agent vs. session storage +- Event-driven architecture: all agent activity is observable via events +- Extensible tool system: tools are first-class objects with execution logic +- Immutable core: low-level loop operates on pure data structures +- Flexible queuing: support for steering and follow-up message queues + +## 3. Alternatives Considered + +| Alternative | Pros | Cons | Decision | +|-------------|------|------|----------| +| **Single monolithic agent class** | Simple to understand, no architectural complexity | Hard to test, difficult to extend, state management becomes complex | Rejected - would not scale for complex deployments | +| **Actor-based concurrency** | Built-in concurrency model, isolation | Heavy overhead, different semantics than required | Rejected - Julia's async primitives sufficient | +| **Callback-based event system** | Familiar pattern, lightweight | Difficult to manage subscriptions, error handling complex | Rejected - Julia's async channels better suited | +| **Full actor model (e.g., GenStage)** | Strong guarantees, backpressure | Overkill for this use case, learning curve | Rejected - simpler event streaming sufficient | + +## 4. High-Level Component Diagram + +```mermaid +%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#3b82f6'}}}%% +flowchart TB + subgraph "User Layer" + A[User Request] + B[Event Subscriber] + end + + subgraph "Agent Layer" + C[Agent] + D[AgentState] + E[PendingMessageQueue] + end + + subgraph "AgentLoop Layer" + F[agentLoop] + G[AgentContext] + H[AgentLoopConfig] + end + + subgraph "Tool Layer" + I[Bash Tool] + J[Read Tool] + K[Write Tool] + L[Edit Tool] + end + + subgraph "Session Layer" + M[Session Storage] + N[JSONL Repo] + O[InMemory Repo] + end + + A --> C + B -->|event stream| C + C --> D + C --> E + C -->|start loop| F + F --> G + F --> H + F -->|execute tool| I + F -->|execute tool| J + F -->|execute tool| K + F -->|execute tool| L + C -->|persist state| M + M --> N + M --> O +``` + +**Component Descriptions**: + +- **Agent** (FR-001, FR-004): High-level interface that manages conversation state, event subscriptions, and message queues. Acts as a facade over the agent loop. + +- **AgentLoop** (FR-002): Low-level execution engine that handles LLM calls, tool execution, and event emission. Operates on pure data structures. + +- **Session Storage** (FR-003): Persists conversation history and metadata. Supports both JSONL file storage and in-memory storage for testing. + +- **Tools** (FR-002): Executable units that perform actions like bash commands, file operations, and database queries. Each tool has execute logic and optional argument preparation. + +- **Event System** (FR-004): Publish-subscribe mechanism for observing agent activity. Enables monitoring, debugging, and external integration. + +## 5. Decision Rationale + +| Decision ID | Decision | Rationale | Alternatives Rejected | +|-------------|----------|-----------|----------------------| +| **SD-001**: Separate Agent and AgentLoop | Clear separation of concerns with Agent managing state and AgentLoop handling execution | Keeps low-level loop pure and testable | Combined class would mix concerns and reduce testability | +| **SD-002**: Event-driven architecture | Enables monitoring, debugging, and extensibility without modifying core logic | Callbacks would be harder to manage and compose | Direct method calls would require tight coupling | +| **SD-003**: JSONL-based persistence | Simple, human-readable format with good Julia ecosystem support | Binary formats would be harder to debug and inspect | Database dependency would complicate deployment | +| **SD-004**: Julia type system for type safety | Compile-time guarantees, better IDE support, clearer intent | Runtime checks would be less robust | Dynamic typing would increase bugs in production | +| **SD-005**: Two-level queuing (steering vs. follow-up) | Supports both immediate conversation correction and post-completion follow-ups | Single queue would not support both use cases | Complex state machine would be needed | +| **SD-006**: Branch-based session navigation | Enables experiment tracking, rollback, and parallel conversation paths | Linear history would not support A/B testing | Version control system would be overkill | + +## 6. Risk Assessment + +| Risk | Impact | Probability | Mitigation | +|------|--------|-------------|------------| +| **R-001**: Performance degradation with large sessions | High | Medium | Implement session compaction, provide metrics for monitoring | +| **R-002**: Tool execution failures breaking conversation | High | Medium | Graceful error handling, retry logic, clear error messages to LLM | +| **R-003**: Data loss from storage failures | High | Low | Support multiple storage backends, implement backup procedures | +| **R-004**: Event system overwhelming subscribers | Medium | Medium | Implement backpressure, provide filtering options, limit event queue size | +| **R-005**: Context window exhaustion | Medium | Medium | Automatic compaction, configurable retention policies, monitoring | + +## 7. Requirements Traceability + +| Solution Component | Requirement ID | Decision ID | Description | +|-------------------|----------------|-------------|-------------| +| Agent struct | FR-001 | SD-001 | Manages conversation state with message history and tools | +| AgentLoop execution | FR-002 | SD-002 | Executes LLM calls and tool calls with proper state handling | +| Session persistence | FR-003 | SD-003 | JSONL storage with repo abstraction for flexibility | +| Event system | FR-004 | SD-002 | Publish-subscribe events for monitoring and debugging | +| Queuing system | FR-005 | SD-005 | Steering and follow-up queues for conversation management | +| Tool framework | FR-002 | SD-002 | Executable tools with error handling and result reporting | +| Compaction | FR-003 | SD-003 | Session history management to fit context windows | + +## 8. Implementation Guidance + +**Module Structure**: +- `src/types.jl`: Core data types and interfaces +- `src/agent_loop.jl`: Low-level execution engine +- `src/agent.jl`: High-level Agent wrapper +- `src/session/`: Session persistence layer +- `src/tools/`: Built-in tool implementations +- `src/messages.jl`: Message transformation logic + +**Key Patterns**: +- Use Julia's multiple dispatch for extensible tool system +- Implement async channels for event streaming +- Use immutable data structures where possible for safety +- Provide both synchronous and asynchronous APIs +- Design for testability with pure functions in low-level modules diff --git a/docs/specification.md b/docs/specification.md new file mode 100644 index 0000000..cbf13df --- /dev/null +++ b/docs/specification.md @@ -0,0 +1,447 @@ +# Specification: AgentCore.jl Technical Contract + +This specification defines the precise technical contracts for the AgentCore.jl system, mapping implementation details to requirements and solution design decisions. + +## 1. Agent State Types + +### 1.1 AgentState + +**Requirement Reference**: FR-001 (Agent State Management) + +The `AgentState` struct maintains conversation state with the following fields: + +| Field | Type | Description | Requirement ID | +|-------|------|-------------|----------------| +| `system_prompt` | `String` | System prompt for the LLM | FR-001 | +| `model` | `Model` | Current model configuration | FR-001 | +| `thinking_level` | `ThinkingLevel` | Thinking mode for LLM | FR-001 | +| `tools` | `Vector{AgentTool}` | Available tools for execution | FR-001 | +| `messages` | `Vector{AgentMessage}` | Conversation history | FR-001 | +| `is_streaming` | `Bool` | Streaming state | FR-004 | +| `streaming_message` | `Union{AgentMessage, Nothing}` | Current streaming message | FR-004 | +| `pending_tool_calls` | `Set{String}` | Active tool call IDs | FR-002 | +| `error_message` | `Union{String, Nothing}` | Current error state | FR-002 | + +**Specification ID**: SPEC-1.1 + +### 1.2 ThinkingLevel Enum + +**Requirement Reference**: FR-001 + +| Value | Description | Use Case | +|-------|-------------|----------| +| `THINKING_OFF` | No thinking mode | Simple Q&A | +| `THINKING_MINIMAL` | Minimal chain of thought | Quick decisions | +| `THINKING_LOW` | Low reasoning effort | Standard operations | +| `THINKING_MEDIUM` | Moderate reasoning | Complex problems | +| `THINKING_HIGH` | High reasoning | Difficult reasoning | +| `THINKING_XHIGH` | Extended reasoning | Multi-step problems | +| `THINKING_MAX` | Maximum reasoning | Critical decisions | + +**Specification ID**: SPEC-1.2 + +### 1.3 ToolExecutionMode Enum + +**Requirement Reference**: FR-002 + +| Value | Description | +|-------|-------------| +| `EXECUTION_SEQUENTIAL` | Execute tools one at a time | +| `EXECUTION_PARALLEL` | Execute tools concurrently | + +**Specification ID**: SPEC-1.3 + +### 1.4 Message Content Types + +**Requirement Reference**: FR-001 + +| Type | Fields | Description | +|------|--------|-------------| +| `TextContent` | `text::String` | Plain text content | +| `ImageContent` | `data::String, mime_type::String` | Base64-encoded image | + +**Specification ID**: SPEC-1.4 + +## 2. Message Types + +### 2.1 AgentMessage Union Type + +**Requirement Reference**: FR-001 + +Abstract type for all agent messages. Concrete types include: + +| Type | Role | Description | +|------|------|-------------| +| `UserMessage` | user | User input messages | +| `AssistantMessage` | assistant | LLM responses | +| `ToolResultMessage` | toolResult | Tool execution results | + +**Specification ID**: SPEC-2.1 + +### 2.2 UserMessage + +**Requirement Reference**: FR-001 + +| Field | Type | Description | Requirement ID | +|-------|------|-------------|----------------| +| `role` | `String` | Always "user" | FR-001 | +| `content` | `Vector{MessageContent}` | Message content (text, images) | FR-001 | +| `timestamp` | `Timestamp` | Creation timestamp | FR-001 | + +**Specification ID**: SPEC-2.2 + +### 2.3 AssistantMessage + +**Requirement Reference**: FR-001, FR-002 + +| Field | Type | Description | Requirement ID | +|-------|------|-------------|----------------| +| `role` | `String` | Always "assistant" | FR-001 | +| `content` | `Vector{MessageContent}` | Response content | FR-001 | +| `api` | `String` | API identifier | FR-001 | +| `provider` | `String` | LLM provider name | FR-001 | +| `model` | `String` | Model identifier | FR-001 | +| `usage` | `Usage` | Token usage statistics | FR-001 | +| `stop_reason` | `String` | Reason for completion | FR-002 | +| `error_message` | `Union{String, Nothing}` | Error details if failed | FR-002 | +| `timestamp` | `Timestamp` | Response timestamp | FR-001 | + +**Specification ID**: SPEC-2.3 + +### 2.4 ToolResultMessage + +**Requirement Reference**: FR-002 + +| Field | Type | Description | Requirement ID | +|-------|------|-------------|----------------| +| `role` | `String` | Always "toolResult" | FR-002 | +| `tool_call_id` | `String` | ID of tool call | FR-002 | +| `tool_name` | `String` | Name of tool | FR-002 | +| `content` | `Vector{MessageContent}` | Tool result content | FR-002 | +| `details` | `Any` | Tool-specific details | FR-002 | +| `usage` | `Union{Usage, Nothing}` | Tool execution usage | FR-002 | +| `added_tool_names` | `Union{Vector{String}, Nothing}` | Newly available tools | FR-002 | +| `is_error` | `Bool` | Whether tool failed | FR-002 | +| `timestamp` | `Timestamp` | Result timestamp | FR-002 | + +**Specification ID**: SPEC-2.4 + +## 3. Tool Interface + +### 3.1 AgentTool + +**Requirement Reference**: FR-002, Solution Design SD-002 + +Tools are defined by the `AgentTool` struct: + +| Field | Type | Description | Requirement ID | +|-------|------|-------------|----------------| +| `name` | `String` | Tool identifier | FR-002 | +| `label` | `String` | Human-readable label | FR-002 | +| `description` | `String` | Tool purpose description | FR-002 | +| `parameters` | `Any` | Parameter schema | FR-002 | +| `execute` | `Function` | Tool execution function | FR-002 | +| `prepare_arguments` | `Union{Function, Nothing}` | Argument transformation | FR-002 | +| `execution_mode` | `Union{ToolExecutionMode, Nothing}` | Execution strategy | FR-002, SD-004 | + +**Specification ID**: SPEC-3.1 + +### 3.2 Tool Execution Contract + +**Requirement Reference**: FR-002, Solution Design SD-002 + +The `execute` function signature: +```julia +execute( + tool_call_id::String, + arguments::Any, + signal::Union{Nothing, AbortSignal}, + on_update::Function +)::AgentToolResult +``` + +**Specification ID**: SPEC-3.2 + +## 4. Session Storage Interface + +### 4.1 SessionTreeEntry + +**Requirement Reference**: FR-003 + +Abstract type for session history entries: + +| Type | Description | +|------|-------------| +| `MessageEntry` | Conversation message | +| `ThinkingLevelChangeEntry` | Thinking level change | +| `ModelChangeEntry` | Model configuration change | +| `ActiveToolsChangeEntry` | Tool availability change | +| `CompactionEntry` | History compaction | +| `BranchSummaryEntry` | Branch summary | +| `CustomEntry` | Custom entry type | +| `LabelEntry` | Entry label | +| `SessionInfoEntry` | Session metadata | +| `LeafEntry` | Current session leaf | + +**Specification ID**: SPEC-4.1 + +### 4.2 JsonlSessionStorage Interface + +**Requirement Reference**: FR-003, Solution Design SD-003 + +Required methods: + +| Method | Returns | Description | +|--------|---------|-------------| +| `getMetadata()` | `SessionMetadata` | Session metadata | +| `appendEntry(entry)` | `Nothing` | Add history entry | +| `getEntry(id)` | `Union{SessionTreeEntry, Nothing}` | Retrieve entry by ID | +| `findEntries(type)` | `Vector{SessionTreeEntry}` | Find entries by type | +| `getSessionStats()` | `SessionStats` | Session statistics | +| `getEntries(options)` | `Vector{SessionTreeEntry}` | Query entries | + +**Specification ID**: SPEC-4.2 + +### 4.3 SessionStats + +**Requirement Reference**: FR-003 + +| Field | Type | Description | +|-------|------|-------------| +| `message_count` | `Int64` | Number of messages | +| `cached_tokens` | `Int64` | Cached token count | +| `uncached_tokens` | `Int64` | Uncached token count | +| `total_tokens` | `Int64` | Total tokens processed | +| `cost_total` | `Float64` | Total cost | + +**Specification ID**: SPEC-4.3 + +## 5. Event System + +### 5.1 Agent Event Types + +**Requirement Reference**: FR-004 + +| Event | Description | Fields | +|-------|-------------|--------| +| `AgentStartEvent` | Agent started | - | +| `AgentEndEvent` | Agent completed | `messages::Vector{AgentMessage}` | +| `TurnStartEvent` | New conversation turn | - | +| `TurnEndEvent` | Conversation turn completed | `message`, `tool_results` | +| `MessageStartEvent` | Message started | `message` | +| `MessageEndEvent` | Message completed | `message` | +| `ToolExecutionStartEvent` | Tool execution started | `tool_call_id`, `tool_name`, `args` | +| `ToolExecutionEndEvent` | Tool execution completed | `tool_call_id`, `tool_name`, `result`, `is_error` | + +**Specification ID**: SPEC-5.1 + +### 5.2 Event Subscription API + +**Requirement Reference**: FR-004 + +```julia +subscribe(agent::Agent, listener::Function)::Function +``` + +- Returns unsubscription function +- Listener signature: `(event::AgentEvent, signal::AbortSignal) -> Nothing` +- Events broadcast to all subscribers concurrently + +**Specification ID**: SPEC-5.2 + +## 6. API Endpoints + +### 6.1 Agent Methods + +**Requirement Reference**: FR-001, FR-005 + +| Method | Parameters | Returns | Description | +|--------|------------|---------|-------------| +| `prompt(agent, input)` | `input::Union{String, AgentMessage, Vector{AgentMessage}}` | `Nothing` | Start new prompt | +| `continue!(agent)` | - | `Nothing` | Continue from last message | +| `steer(agent, message)` | `message::AgentMessage` | `Nothing` | Queue steering message | +| `followUp(agent, message)` | `message::AgentMessage` | `Nothing` | Queue follow-up message | +| `reset!(agent)` | - | `Nothing` | Clear all state | +| `get_state(agent)` | - | `AgentState` | Get current state | +| `subscribe(agent, listener)` | `listener::Function` | `Function` | Subscribe to events | + +**Specification ID**: SPEC-6.1 + +### 6.2 AgentLoop Functions + +**Requirement Reference**: FR-002, Solution Design SD-001 + +| Function | Parameters | Returns | Description | +|----------|------------|---------|-------------| +| `agentLoop()` | `prompts, context, config, signal, stream_fn` | `EventStream` | Run agent loop | +| `agentLoopContinue()` | `context, config, signal, stream_fn` | `EventStream` | Continue agent loop | +| `streamAssistantResponse()` | `context, config, signal, emit, stream_fn` | `AssistantMessage` | Stream LLM response | + +**Specification ID**: SPEC-6.2 + +## 7. Error Codes + +### 7.1 Agent Errors + +**Requirement Reference**: FR-001, FR-002 + +| Code | Description | +|------|-------------| +| `AGENT_BUSY` | Agent already processing | +| `INVALID_MESSAGE_ROLE` | Invalid message role for operation | +| `AGENT_NOT_FOUND` | Session not found | +| `TOOL_NOT_FOUND` | Tool not registered | + +**Specification ID**: SPEC-7.1 + +### 7.2 Tool Errors + +**Requirement Reference**: FR-002 + +| Code | Description | +|------|-------------| +| `EXECUTION_TIMEOUT` | Tool execution timed out | +| `EXECUTION_ABORTED` | Tool execution aborted | +| `TOOL_NOT_SUPPORTED` | Tool not available | +| `INVALID_PARAMETERS` | Tool parameters invalid | + +**Specification ID**: SPEC-7.2 + +## 8. Data Validation Rules + +### 8.1 Message Content + +**Requirement Reference**: FR-001, FR-002 + +| Constraint | Rule | +|------------|------| +| `TextContent.text` | Must be non-empty string | +| `ImageContent.data` | Must be valid Base64 | +| `ImageContent.mime_type` | Must be valid MIME type | +| `AgentMessage.timestamp` | Must be positive integer | + +**Specification ID**: SPEC-8.1 + +### 8.2 Tool Arguments + +**Requirement Reference**: FR-002 + +| Constraint | Rule | +|------------|------| +| `AgentTool.name` | Must match regex `^[a-zA-Z_][a-zA-Z0-9_]*$` | +| `AgentTool.description` | Must be non-empty string | +| `execute` function | Must return `AgentToolResult` | + +**Specification ID**: SPEC-8.2 + +## 9. Rate Limiting + +### 9.1 Message Processing + +**Requirement Reference**: NFR-101 + +| Metric | Limit | +|--------|-------| +| Messages per session | 1000 per conversation | +| Messages per minute | 100 per session | +| Tool calls per turn | 10 concurrent | + +**Specification ID**: SPEC-9.1 + +### 9.2 Storage Operations + +**Requirement Reference**: NFR-101 + +| Operation | Rate Limit | +|-----------|------------| +| Read operations | 1000 per second | +| Write operations | 100 per second | + +**Specification ID**: SPEC-9.2 + +## 10. Configuration + +### 10.1 Agent Options + +**Requirement Reference**: FR-001, FR-005 + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `systemPrompt` | `String` | `""` | System prompt | +| `model` | `Model` | Required | LLM model config | +| `thinkingLevel` | `ThinkingLevel` | `THINKING_OFF` | Thinking mode | +| `tools` | `Vector{AgentTool}` | `[]` | Available tools | +| `messages` | `Vector{AgentMessage}` | `[]` | Initial messages | +| `steeringMode` | `QueueMode` | `QUEUE_ONE_AT_A_TIME` | Steering queue mode | +| `followUpMode` | `QueueMode` | `QUEUE_ONE_AT_A_TIME` | Follow-up queue mode | +| `toolExecution` | `ToolExecutionMode` | `EXECUTION_PARALLEL` | Tool execution mode | + +**Specification ID**: SPEC-10.1 + +### 10.2 Session Options + +**Requirement Reference**: FR-003, Solution Design SD-003 + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `cwd` | `String` | Current directory | Working directory | +| `path` | `String` | Required | Session storage path | +| `metadata` | `Dict{String, Any}` | `{}` | Session metadata | + +**Specification ID**: SPEC-10.2 + +## 11. Performance Specifications + +### 11.1 Latency Targets + +**Requirement Reference**: NFR-101, KPI-001 + +| Operation | Target Latency | 95th Percentile | 99th Percentile | +|-----------|---------------|-----------------|-----------------| +| Message processing | 200ms | 500ms | 1000ms | +| Tool execution | 500ms | 2000ms | 5000ms | +| Session recovery | 2000ms | 5000ms | 10000ms | + +**Specification ID**: SPEC-11.1 + +### 11.2 Throughput + +**Requirement Reference**: NFR-102 + +| Metric | Target | +|--------|--------| +| Concurrent sessions | 100 | +| Messages per session per hour | 1000 | +| Tool calls per minute | 100 | + +**Specification ID**: SPEC-11.2 + +## 12. Traceability Summary + +### 12.1 Requirement to Specification Mapping + +| Requirement ID | Specification Section | Description | +|----------------|----------------------|-------------| +| FR-001 | SPEC-1.x, SPEC-2.x, SPEC-6.1 | Agent state management | +| FR-002 | SPEC-1.x, SPEC-2.x, SPEC-3.x, SPEC-6.2 | Tool execution | +| FR-003 | SPEC-4.x, SPEC-10.2 | Session persistence | +| FR-004 | SPEC-5.x, SPEC-6.1 | Event streaming | +| FR-005 | SPEC-1.x, SPEC-6.1 | Conversation management | +| FR-006 | N/A | Wine database (external) | +| NFR-101 | SPEC-11.x | Performance | +| NFR-102 | SPEC-11.x | Scalability | +| NFR-201 | SPEC-4.x, SPEC-6.1 | Availability | + +**Specification ID**: SPEC-12.1 + +### 12.2 Solution Design to Specification Mapping + +| Decision ID | Specification Section | Implementation | +|-------------|----------------------|----------------| +| SD-001 | SPEC-6.2 | AgentLoop functions | +| SD-002 | SPEC-3.x, SPEC-5.x | Tool interface, event system | +| SD-003 | SPEC-4.x | Session storage | +| SD-004 | SPEC-1.3, SPEC-3.1 | Tool execution modes | +| SD-005 | SPEC-6.1 | Queuing methods | + +**Specification ID**: SPEC-12.2 diff --git a/docs/walkthrough.md b/docs/walkthrough.md new file mode 100644 index 0000000..05be34b --- /dev/null +++ b/docs/walkthrough.md @@ -0,0 +1,559 @@ +# 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