ton/YiemAgent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

add docs

Browse Source
This commit is contained in:
narawat
2026-07-28 08:12:15 +07:00
parent 984a678d92
commit 1bda81bb08
5 changed files with 1389 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
ai_system_prompt.md → .AI_prompt.md
+45
View File
@@ -80,3 +80,48 @@ Assistant should only respond in JSON format as described below:
"action_input": "..."
}
```
<!-- ------------------------------------------- 100 ------------------------------------------- -->
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
docs/requirements.md
+190
View File
@@ -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
docs/solution-design.md
+148
View File
@@ -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
docs/specification.md
+447
View File
@@ -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
docs/walkthrough.md
+559
View File
@@ -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