448 lines
14 KiB
Markdown
448 lines
14 KiB
Markdown
# 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
|