YiemAgent/docs/specification.md

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:

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

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