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

ีupdate

Browse Source
This commit is contained in:
narawat
2026-07-29 13:50:00 +07:00
parent efa18ba800
commit 8fd72f8d37
7 changed files with 214 additions and 214 deletions
Download Patch File Download Diff File Expand all files Collapse all files
learning/01-ARCHITECTURE_OVERVIEW.md
+90 -90
View File
@@ -51,7 +51,7 @@
``` ```
┌─────────────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────────────┐
│ Agent Lifecycle │ │ Agent Lifecycle │
└─────────────────────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────────────────┘
User Code User Code
@@ -83,20 +83,20 @@
▼ ▼
┌──────────────────────────────────────────────────────────────┐ ┌──────────────────────────────────────────────────────────────┐
│ AgentLoop (runs in separate thread) │ │ AgentLoop (runs in separate thread) │
│ │ │ │
│ ┌────────────────────────────────────────────────────────┐ │ │ ┌────────────────────────────────────────────────────────┐ │
│ │ 1. Emit AgentStartEvent │ │ │ │ 1. Emit AgentStartEvent │ │
│ │ 2. Emit TurnStartEvent │ │ │ │ 2. Emit TurnStartEvent │ │
│ │ 3. Process prompts (emit MessageStart/End) │ │ │ │ 3. Process prompts (emit MessageStart/End) │ │
│ │ 4. ┌──────────────────────────────────────────────┐ │ │ │ │ 4.┌────────────────────────────────────────────────┐ │ │
│ │ │ while true: │ │ │ │ │ │ while true: │ │ │
│ │ │ │ Process steering/follow-up messages │ │ │ │ │ │ │ Process steering/follow-up messages │ │ │
│ │ │ │ Stream assistant response (LLM call) │ │ │ │ │ │ │ Stream assistant response (LLM call) │ │ │
│ │ │ │ Execute tool calls (parallel/sequential) │ │ │ │ │ │ │ Execute tool calls (parallel/sequential) │ │ │
│ │ │ │ Emit TurnEndEvent │ │ │ │ │ │ │ Emit TurnEndEvent │ │ │
│ │ │ │ Check if should stop │ │ │ │ │ │ │ Check if should stop │ │ │
│ │ │ │ Get next steering messages │ │ │ │ │ │ │ Get next steering messages │ │ │
│ │ └───┴────────────────────────────────────────────┘ │ │ │ │ └───┴────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────┘ │ │ └────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘ └──────────────────────────────────────────────────────────────┘
│ │
@@ -125,18 +125,18 @@
│ ┌────────────────────────────────────────────────────────────┐ │ │ ┌────────────────────────────────────────────────────────────┐ │
│ │ agentLoop(prompts, context, config, signal, stream_fn) │ │ │ │ agentLoop(prompts, context, config, signal, stream_fn) │ │
│ └────────────────────────────────────────────────────────────┘ │ │ └────────────────────────────────────────────────────────────┘ │
│ │ │ │ │ │
│ ▼ │ │ ▼ │
│ ┌────────────────────────────────────────────────────────────┐ │ │ ┌────────────────────────────────────────────────────────────┐ │
│ │ runAgentLoop(prompts, context, config, emit, signal) │ │ │ │ runAgentLoop(prompts, context, config, emit, signal) │ │
│ └────────────────────────────────────────────────────────────┘ │ │ └────────────────────────────────────────────────────────────┘ │
│ │ │ │ │ │
│ ▼ │ │ ▼ │
│ ┌────────────────────────────────────────────────────────────┐ │ │ ┌────────────────────────────────────────────────────────────┐ │
│ │ runLoop() - Main Event Loop │ │ │ │ runLoop() - Main Event Loop │ │
│ └────────────────────────────────────────────────────────────┘ │ │ └────────────────────────────────────────────────────────────┘ │
│ │ │ │ │ │
└──────────────────────────────┼───────────────────────────────────────┘ └──────────────────────────────┼─────────────────────────────────────┘
│ │
│ Loop Iteration │ Loop Iteration
▼ ▼
@@ -150,8 +150,8 @@
│ │ │ (after assistant) │ │ (after stop) │ │ │ │ │ │ (after assistant) │ │ (after stop) │ │ │
│ │ └────────────────────┘ └──────────────────────┘ │ │ │ │ └────────────────────┘ └──────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────┘ │ │ └────────────────────────────────────────────────────────────┘ │
│ │ │ │ │ │
│ ▼ │ │ ▼ │
│ ┌────────────────────────────────────────────────────────────┐ │ │ ┌────────────────────────────────────────────────────────────┐ │
│ │ 2. Stream Assistant Response │ │ │ │ 2. Stream Assistant Response │ │
│ │ ┌────────────────────────────────────────────────────┐ │ │ │ │ ┌────────────────────────────────────────────────────┐ │ │
@@ -161,39 +161,39 @@
│ │ │ - Text deltas │ │ │ │ │ │ - Text deltas │ │ │
│ │ │ - Tool call deltas │ │ │ │ │ │ - Tool call deltas │ │ │
│ │ └────────────────────────────────────────────────────┘ │ │ │ │ └────────────────────────────────────────────────────┘ │ │
│ │ │ │ │ │ │ │ │ │
│ │ ▼ │ │ │ │ ▼ │ │
│ │ ┌────────────────────────────────────────────────────┐ │ │ │ │ ┌────────────────────────────────────────────────────┐ │ │
│ │ │ Emit: MessageStartEvent, MessageUpdateEvent, │ │ │ │ │ │ Emit: MessageStartEvent, MessageUpdateEvent, │ │ │
│ │ │ MessageEndEvent │ │ │ │ │ │ MessageEndEvent │ │ │
│ │ └────────────────────────────────────────────────────┘ │ │ │ │ └────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────┘ │ │ └────────────────────────────────────────────────────────────┘ │
│ │ │ │ │ │
│ ▼ │ │ ▼ │
│ ┌────────────────────────────────────────────────────────────┐ │ │ ┌────────────────────────────────────────────────────────────┐ │
│ │ 3. Execute Tool Calls │ │ │ │ 3. Execute Tool Calls │ │
│ │ ┌────────────────────────────────────────────────────┐ │ │ │ │ ┌────────────────────────────────────────────────────┐ │ │
│ │ │ extract ToolCall from assistant content │ │ │ │ │ │ extract ToolCall from assistant content │ │ │
│ │ │ │ │ │ │ │ │ │ │ │
│ │ │ if EXECUTION_SEQUENTIAL || has_sequential_tool: │ │ │ │ │ │ if EXECUTION_SEQUENTIAL || has_sequential_tool: │ │ │
│ │ │ executeToolCallsSequential() │ │ │ │ │ │ executeToolCallsSequential() │ │ │
│ │ │ else: │ │ │ │ │ │ else: │ │ │
│ │ │ executeToolCallsParallel() │ │ │ │ │ │ executeToolCallsParallel() │ │ │
│ │ └────────────────────────────────────────────────────┘ │ │ │ │ └────────────────────────────────────────────────────┘ │ │
│ │ │ │ │ │ │ │ │ │
│ │ ▼ │ │ │ │ ▼ │ │
│ │ ┌────────────────────────────────────────────────────┐ │ │ │ │ ┌────────────────────────────────────────────────────┐ │ │
│ │ │ For each tool call: │ │ │ │ │ │ For each tool call: │ │ │
│ │ │ 1. before_tool_call hook │ │ │ │ │ │ 1. before_tool_call hook │ │ │
│ │ │ 2. prepareToolCall() │ │ │ │ │ │ 2. prepareToolCall() │ │ │
│ │ │ 3. execute() │ │ │ │ │ │ 3. execute() │ │ │
│ │ │ 4. after_tool_call hook │ │ │ │ │ │ 4. after_tool_call hook │ │ │
│ │ │ 5. Emit ToolExecutionStart/Update/EndEvent │ │ │ │ │ │ 5. Emit ToolExecutionStart/Update/EndEvent │ │ │
│ │ │ 6. Emit ToolResultMessage │ │ │ │ │ │ 6. Emit ToolResultMessage │ │ │
│ │ └────────────────────────────────────────────────────┘ │ │ │ │ └────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────┘ │ │ └────────────────────────────────────────────────────────────┘ │
│ │ │ │ │ │
│ ▼ │ │ ▼ │
│ ┌────────────────────────────────────────────────────────────┐ │ │ ┌────────────────────────────────────────────────────────────┐ │
│ │ 4. Prepare Next Turn │ │ │ │ 4. Prepare Next Turn │ │
│ │ ┌────────────────────────────────────────────────────┐ │ │ │ │ ┌────────────────────────────────────────────────────┐ │ │
@@ -202,29 +202,29 @@
│ │ │ - Optional: Update context │ │ │ │ │ │ - Optional: Update context │ │ │
│ │ └────────────────────────────────────────────────────┘ │ │ │ │ └────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────┘ │ │ └────────────────────────────────────────────────────────────┘ │
│ │ │ │ │ │
│ ▼ │ │ ▼ │
│ ┌────────────────────────────────────────────────────────────┐ │ │ ┌────────────────────────────────────────────────────────────┐ │
│ │ 5. Check Termination Conditions │ │ │ │ 5. Check Termination Conditions │ │
│ │ ┌────────────────────────────────────────────────────┐ │ │ │ │ ┌────────────────────────────────────────────────────┐ │ │
│ │ │ should_stop_after_turn(context) -> bool │ │ │ │ │ │ should_stop_after_turn(context) -> bool │ │ │
│ │ │ - Max turns reached? │ │ │ │ │ │ - Max turns reached? │ │ │
│ │ │ - Tool returned terminate=true? │ │ │ │ │ │ - Tool returned terminate=true? │ │ │
│ │ │ - Steering queue empty and follow-up empty? │ │ │ │ │ │ - Steering queue empty and follow-up empty? │ │ │
│ │ └────────────────────────────────────────────────────┘ │ │ │ │ └────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────┘ │ │ └────────────────────────────────────────────────────────────┘ │
│ │ │ │ │ │
│ ▼ │ │ ▼ │
│ ┌────────────────────────────────────────────────────────────┐ │ │ ┌────────────────────────────────────────────────────────────┐ │
│ │ 6. Emit TurnEndEvent (message, tool_results) │ │ │ │ 6. Emit TurnEndEvent (message, tool_results) │ │
│ └────────────────────────────────────────────────────────────┘ │ │ └────────────────────────────────────────────────────────────┘ │
│ │ │ │ │ │
│ ▼ │ │ ▼ │
│ ┌────────────────────────────────────────────────────────────┐ │ │ ┌────────────────────────────────────────────────────────────┐ │
│ │ Loop continues until termination condition met │ │ │ │ Loop continues until termination condition met │ │
│ └────────────────────────────────────────────────────────────┘ │ │ └────────────────────────────────────────────────────────────┘ │
│ │ │ │ │ │
└──────────────────────────────┼───────────────────────────────────────┘ └──────────────────────────────┼─────────────────────────────────────┘
│ │
▼ ▼
┌────────────────────────────────────────────────────────────────────┐ ┌────────────────────────────────────────────────────────────────────┐
@@ -240,34 +240,34 @@
└─────────────────────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────────────────┘
┌───────────────────────────────────────────────────────────────────┐ ┌───────────────────────────────────────────────────────────────────┐
│ Assistant Message with Tool Calls │ │ Assistant Message with Tool Calls │
│ ┌─────────────────────────────────────────────────────────────┐ │ │ ┌─────────────────────────────────────────────────────────────┐ │
│ │ AssistantMessage: │ │ │ │ AssistantMessage: │ │
│ │ content: [ │ │ │ │ content: [ │ │
│ │ TextContent("I'll help you"), │ │ │ │ TextContent("I'll help you"), │ │
│ │ ToolCall(id="tc1", name="bash", args={...}), │ │ │ │ ToolCall(id="tc1", name="bash", args={...}), │ │
│ │ ToolCall(id="tc2", name="read", args={...}) │ │ │ │ ToolCall(id="tc2", name="read", args={...}) │ │
│ │ ] │ │ │ │ ] │ │
│ └─────────────────────────────────────────────────────────────┘ │ │ └─────────────────────────────────────────────────────────────┘ │
│ │ │ │ │ │
│ ▼ │ │ ▼ │
└───────────────────────────────────────────────────────────────────┘ └───────────────────────────────────────────────────────────────────┘
│ │
│ executeToolCalls() │ executeToolCalls()
▼ ▼
┌───────────────────────────────────────────────────────────────────┐ ┌───────────────────────────────────────────────────────────────────┐
│ Determine Execution Mode │ │ Determine Execution Mode │
│ ┌─────────────────────────────────────────────────────────────┐ │ │ ┌─────────────────────────────────────────────────────────────┐ │
│ │ config.tool_execution == EXECUTION_SEQUENTIAL? │ │ │ │ config.tool_execution == EXECUTION_SEQUENTIAL? │ │
│ │ OR any tool has execution_mode == EXECUTION_SEQUENTIAL? │ │ │ │ OR any tool has execution_mode == EXECUTION_SEQUENTIAL? │ │
│ └─────────────────────────────────────────────────────────────┘ │ │ └─────────────────────────────────────────────────────────────┘ │
│ │ │ │ │ │
│ ┌───────────────┴───────────────┐ │ │ ┌───────────────┴───────────────┐ │
│ ▼ ▼ │ │ ▼ ▼ │
│ ┌────────────────────────┐ ┌────────────────────────┐ │ │ ┌────────────────────────┐ ┌────────────────────────┐ │
│ │ executeSequential() │ │ executeParallel() │ │ │ │ executeSequential() │ │ executeParallel() │ │
│ └────────────────────────┘ └────────────────────────┘ │ │ └────────────────────────┘ └────────────────────────┘ │
│ │ │ │ │ │ │ │
└──────────────┼───────────────────────────────┼────────────────────┘ └──────────────┼───────────────────────────────┼────────────────────┘
│ │ │ │
│ │ │ │
@@ -285,7 +285,7 @@
│ │
▼ ▼
┌───────────────────────────────────────────────────────────────────┐ ┌───────────────────────────────────────────────────────────────────┐
│ For Each Tool Call │ │ For Each Tool Call │
│ ┌─────────────────────────────────────────────────────────────┐ │ │ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 1. before_tool_call hook (optional) │ │ │ │ 1. before_tool_call hook (optional) │ │
│ │ - Can block execution │ │ │ │ - Can block execution │ │
@@ -293,20 +293,20 @@
│ │ - validateToolArguments() │ │ │ │ - validateToolArguments() │ │
│ │ - prepareToolCallArguments() (optional) │ │ │ │ - prepareToolCallArguments() (optional) │ │
│ │ 3. Execute Tool: │ │ │ │ 3. Execute Tool: │ │
│ │ tool.execute(tool_call_id, args, signal, on_update) │ │ │ │ tool.execute(tool_call_id, args, signal, on_update) │ │
│ │ 4. after_tool_call hook (optional) │ │ │ │ 4. after_tool_call hook (optional) │ │
│ │ - Can modify result content │ │ │ │ - Can modify result content │ │
│ │ 5. Emit events: │ │ │ │ 5. Emit events: │ │
│ │ - ToolExecutionStartEvent │ │ │ │ - ToolExecutionStartEvent │ │
│ │ - ToolExecutionUpdateEvent (optional) │ │ │ │ - ToolExecutionUpdateEvent (optional) │ │
│ │ - ToolExecutionEndEvent │ │ │ │ - ToolExecutionEndEvent │ │
│ │ 6. Create ToolResultMessage │ │ │ │ 6. Create ToolResultMessage │ │
│ └─────────────────────────────────────────────────────────────┘ │ │ └─────────────────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────────────┘ └───────────────────────────────────────────────────────────────────┘
│ │
▼ ▼
┌───────────────────────────────────────────────────────────────────┐ ┌───────────────────────────────────────────────────────────────────┐
│ Tool Result Messages │ │ Tool Result Messages │
│ ┌─────────────────────────────────────────────────────────────┐ │ │ ┌─────────────────────────────────────────────────────────────┐ │
│ │ ToolResultMessage: │ │ │ │ ToolResultMessage: │ │
│ │ role: "toolResult" │ │ │ │ role: "toolResult" │ │
@@ -329,47 +329,47 @@
┌───────────────────────────────────────────────────────────────────┐ ┌───────────────────────────────────────────────────────────────────┐
│ Branch Navigation │ │ Branch Navigation │
│ │ │ │
│ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │ │ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │
│ │ E1 │────▶│ E2 │────▶│ E3 │────▶│ E4 │────▶│ E5 │ (leaf) │ │ │ E1 │────▶│ E2 │────▶│ E3 │────▶│ E4 │────▶│ E5 │ (leaf) │
│ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ │ │ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ │
│ │ │ │ │ │ │ │ │ │ │ │ │ │
│ ▼ ▼ ▼ ▼ ▼ │ │ ▼ ▼ ▼ ▼ ▼ │
│ Message Message Compaction Message BranchSummary │ │ Message Message Compaction Message BranchSummary │
│ │ │ │
│ E3 is a Compaction Entry: │ │ E3 is a Compaction Entry: │
│ - Summary of E1, E2 │ │ - Summary of E1, E2 │
│ - first_kept_entry_id: reference to first retained message │ │ - first_kept_entry_id: reference to first retained message │
│ - tokens_before: context size before compaction │ │ - tokens_before: context size before compaction │
│ │ │ │
│ E5 is a BranchSummary Entry: │ │ E5 is a BranchSummary Entry: │
│ - Summary of branch from from_id │ │ - Summary of branch from from_id │
│ - Represents a fork point in conversation history │ │ - Represents a fork point in conversation history │
│ │ │ │
└───────────────────────────────────────────────────────────────────┘ └───────────────────────────────────────────────────────────────────┘
│ │
│ Session.moveTo() │ Session.moveTo()
▼ ▼
┌───────────────────────────────────────────────────────────────────┐ ┌───────────────────────────────────────────────────────────────────┐
│ Forking & Branching │ │ Forking & Branching │
│ │ │ │
│ Current branch: │ │ Current branch: │
│ ┌─────┐ ┌─────┐ ┌─────┐ │ │ ┌─────┐ ┌─────┐ ┌─────┐ │
│ │ E1 │────▶│ E2 │────▶│ E3 │ │ │ │ E1 │────▶│ E2 │────▶│ E3 │ │
│ └─────┘ └─────┘ └─────┘ │ │ └─────┘ └─────┘ └─────┘ │
│ │ │ │ │ │
│ │ moveTo(E2) │ │ │ moveTo(E2) │
│ ▼ │ │ ▼ │
│ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │ │ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │
│ │ E1 │────▶│ E2 │────▶│ E3' │────▶│ E4' │ (new branch) │ │ │ E1 │────▶│ E2 │────▶│ E3' │────▶│ E4' │ (new branch) │
│ └─────┘ └─────┘ └─────┘ └─────┘ │ │ └─────┘ └─────┘ └─────┘ └─────┘ │
│ │ │ │ │ │
│ │ create BranchSummary │ │ │ create BranchSummary │
│ ▼ │ │ ▼ │
│ ┌─────┐ │ │ ┌─────┐ │
│ │ E5 │ (branch summary) │ │ │ E5 │ (branch summary) │
│ └─────┘ │ │ └─────┘ │
│ │ │ │
└───────────────────────────────────────────────────────────────────┘ └───────────────────────────────────────────────────────────────────┘
``` ```
@@ -377,7 +377,7 @@
``` ```
┌─────────────────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────────────────┐
│ Component Relationships │ │ Component Relationships │
└─────────────────────────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────────────────────┘
User Code User Code
@@ -409,7 +409,7 @@
``` ```
┌─────────────────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────────────────┐
│ Data Flow Between Layers │ │ Data Flow Between Layers │
└─────────────────────────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────────────────────┘
User Input (String/Message) User Input (String/Message)
learning/02-AGENT_COMPONENT.md
+5 -5
View File
@@ -403,9 +403,9 @@ Scenario: User sends message, agent responds with tool calls
┌────────────────────────────────────────────────────────────┐ ┌────────────────────────────────────────────────────────────┐
│ Time 2: User queues steering message │ │ Time 2: User queues steering message │
│ ┌──────────────────┐ │ │ ┌──────────────────┐ │
│ │ steer(msg2) │ ──► steering_queue.push(msg2) │ │ │ steer(msg2) │ ──► steering_queue.push(msg2) │
│ └──────────────────┘ │ │ └──────────────────┘ │
│ │ │ │
│ (msg2 not processed yet!) │ │ (msg2 not processed yet!) │
└────────────────────────────────────────────────────────────┘ └────────────────────────────────────────────────────────────┘
│ │
@@ -413,9 +413,9 @@ Scenario: User sends message, agent responds with tool calls
┌────────────────────────────────────────────────────────────┐ ┌────────────────────────────────────────────────────────────┐
│ Time 3: Tool execution │ │ Time 3: Tool execution │
│ ┌──────────────────────────────────────────────────────┐ │ │ ┌──────────────────────────────────────────────────────┐ │
│ │ Execute bash tool... │ │ │ │ Execute bash tool... │ │
│ │ Execute read tool... │ │ │ │ Execute read tool... │ │
│ │ Emit ToolResultMessage[] │ │ │ │ Emit ToolResultMessage[] │ │
│ └──────────────────────────────────────────────────────┘ │ │ └──────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────┘ └────────────────────────────────────────────────────────────┘
│ │
learning/03-AGENTLOOP_COMPONENT.md
+31 -31
View File
@@ -31,55 +31,55 @@ agentLoopContinue()
└─────────────────────────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────────────────┐
│ 1. runAgentLoop() ── Entry point for new conversation │ │ 1. runAgentLoop() ── Entry point for new conversation │
│ - Creates copy of prompts │ │ - Creates copy of prompts │
│ - Appends prompts to context.messages │ │ - Appends prompts to context.messages │
│ - Emits AgentStartEvent │ │ - Emits AgentStartEvent │
│ - Emits TurnStartEvent │ │ - Emits TurnStartEvent │
│ - Emits MessageStart/End for each prompt │ │ - Emits MessageStart/End for each prompt │
│ - Calls runLoop() │ │ - Calls runLoop() │
└─────────────────────────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────────────────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────────────────┐
│ 2. runLoop() ── Main event loop │ │ 2. runLoop() ── Main event loop │
│ ┌────────────────────────────────────────────────────────────────────┐ │ │ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ while true: │ │ │ │ while true: │ │
│ │ 1. Get steering/follow-up messages (if any) │ │ │ │ 1. Get steering/follow-up messages (if any) │ │
│ │ 2. Emit messages as UserMessage │ │ │ │ 2. Emit messages as UserMessage │ │
│ │ 3. streamAssistantResponse() │ │ │ │ 3. streamAssistantResponse() │ │
│ │ 4. Execute tool calls (sequential or parallel) │ │ │ │ 4. Execute tool calls (sequential or parallel) │ │
│ │ 5. Emit TurnEndEvent │ │ │ │ 5. Emit TurnEndEvent │ │
│ │ 6. prepare_next_turn (optional) │ │ │ │ 6. prepare_next_turn (optional) │ │
│ │ 7. should_stop_after_turn? (check termination) │ │ │ │ 7. should_stop_after_turn? (check termination) │ │
│ │ 8. Loop continues if not terminated │ │ │ │ 8. Loop continues if not terminated │ │
│ └────────────────────────────────────────────────────────────────────┘ │ │ └────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────────────────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────────────────┐
│ 3. streamAssistantResponse() ── LLM interaction │ │ 3. streamAssistantResponse() ── LLM interaction │
│ - transform_context (optional) │ │ - transform_context (optional) │
│ - convert_to_llm (transform to Message[]) │ │ - convert_to_llm (transform to Message[]) │
│ - Call stream_fn (LLM API) │ │ - Call stream_fn (LLM API) │
│ - Stream response deltas │ │ - Stream response deltas │
│ - Emit MessageStart/Update/End events │ │ - Emit MessageStart/Update/End events │
└─────────────────────────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────────────────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────────────────┐
│ 4. executeToolCalls() ── Tool execution │ │ 4. executeToolCalls() ── Tool execution │
│ ┌────────────────────────────────────────────────────────────────────┐ │ │ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ if EXECUTION_SEQUENTIAL || has_sequential_tool: │ │ │ │ if EXECUTION_SEQUENTIAL || has_sequential_tool: │ │
│ │ executeToolCallsSequential() │ │ │ │ executeToolCallsSequential() │ │
│ │ else: │ │ │ │ else: │ │
│ │ executeToolCallsParallel() │ │ │ │ executeToolCallsParallel() │ │
│ └────────────────────────────────────────────────────────────────────┘ │ │ └────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────────────────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────────────────┐
│ 5. AgentEndEvent ── Final event with all messages │ │ 5. AgentEndEvent ── Final event with all messages │
└─────────────────────────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────────────────────┘
``` ```
@@ -520,13 +520,13 @@ ToolResultMessage(
┌──────┐ ┌──────┐
│ TC1 │ ──► prepareToolCall() ──► create closure ──► ┐ │ TC1 │ ──► prepareToolCall() ──► create closure ──► ┐
└──────┘ │ └──────┘ │
│ │
┌──────┐ │ ┌──────┐ │
│ TC2 │ ──► prepareToolCall() ──► create closure ──► ├─► All closures queued │ TC2 │ ──► prepareToolCall() ──► create closure ──► ├─► All closures queued
└──────┘ │ └──────┘ │
│ │
┌──────┐ │ ┌──────┐ │
│ TC3 │ ──► prepareToolCall() ──► create closure ──► ┘ │ TC3 │ ──► prepareToolCall() ──► create closure ──► ┘
└──────┘ └──────┘
learning/04-TYPES_MESSAGES.md
+47 -47
View File
@@ -19,80 +19,80 @@
└─────────────────────────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────────────────┐
│ ToolExecutionMode (Enum) │ │ ToolExecutionMode (Enum) │
│ - EXECUTION_SEQUENTIAL (Tools run one at a time) │ │ - EXECUTION_SEQUENTIAL (Tools run one at a time) │
│ - EXECUTION_PARALLEL (Tools run concurrently) │ │ - EXECUTION_PARALLEL (Tools run concurrently) │
└─────────────────────────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────────────────┐
│ QueueMode (Enum) │ │ QueueMode (Enum) │
│ - QUEUE_ALL (Drain all messages at once) │ │ - QUEUE_ALL (Drain all messages at once) │
│ - QUEUE_ONE_AT_A_TIME (Process one message at a time) │ │ - QUEUE_ONE_AT_A_TIME (Process one message at a time) │
└─────────────────────────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────────────────┐
│ MessageContent (Abstract Type) │ │ MessageContent (Abstract Type) │
│ ├── TextContent (String) │ │ ├── TextContent (String) │
│ └── ImageContent (data::String, mime_type::String) │ │ └── ImageContent (data::String, mime_type::String) │
└─────────────────────────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────────────────┐
│ Message (Abstract Type) │ │ Message (Abstract Type) │
│ ├── UserMessage │ │ ├── UserMessage │
│ │ └─ role: "user", content: Message[], timestamp: Int64 │ │ │ └─ role: "user", content: Message[], timestamp: Int64 │
│ ├── AssistantMessage │ │ ├── AssistantMessage │
│ │ └─ role: "assistant", content: Message[], api, provider, model, │ │ │ └─ role: "assistant", content: Message[], api, provider, model, │
│ │ usage: Usage, stop_reason, error_message, timestamp │ │ │ usage: Usage, stop_reason, error_message, timestamp │
│ └── ToolResultMessage │ │ └── ToolResultMessage │
│ └─ role: "toolResult", tool_call_id, tool_name, content, details, │ │ └─ role: "toolResult", tool_call_id, tool_name, content, details, │
│ usage, added_tool_names, is_error, timestamp │ │ usage, added_tool_names, is_error, timestamp │
└─────────────────────────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────────────────┐
│ AgentMessage (Abstract Type) │ │ AgentMessage (Abstract Type) │
│ └─ Union of all message types above + custom types │ │ └─ Union of all message types above + custom types │
└─────────────────────────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────────────────┐
│ AgentTool │ │ AgentTool │
│ - name: String │ │ - name: String │
│ - label: String │ │ - label: String │
│ - description: String │ │ - description: String │
│ - parameters: Any │ │ - parameters: Any │
│ - execute: Function │ │ - execute: Function │
│ - prepare_arguments: Union{Function, Nothing} │ │ - prepare_arguments: Union{Function, Nothing} │
│ - execution_mode: Union{ToolExecutionMode, Nothing} │ │ - execution_mode: Union{ToolExecutionMode, Nothing} │
└─────────────────────────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────────────────┐
│ AgentContext │ │ AgentContext │
│ - system_prompt: String │ │ - system_prompt: String │
│ - messages: Vector{AgentMessage} │ │ - messages: Vector{AgentMessage} │
│ - tools: Union{Vector{AgentTool}, Nothing} │ │ - tools: Union{Vector{AgentTool}, Nothing} │
└─────────────────────────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────────────────┐
│ AgentEvent (Abstract Type) │ │ AgentEvent (Abstract Type) │
│ ├── AgentStartEvent / AgentEndEvent │ │ ├── AgentStartEvent / AgentEndEvent │
│ ├── TurnStartEvent / TurnEndEvent │ │ ├── TurnStartEvent / TurnEndEvent │
│ ├── MessageStartEvent / MessageEndEvent │ │ ├── MessageStartEvent / MessageEndEvent │
│ ├── MessageUpdateEvent │ │ ├── MessageUpdateEvent │
│ ├── ToolExecutionStartEvent / ToolExecutionEndEvent │ │ ├── ToolExecutionStartEvent / ToolExecutionEndEvent │
│ └── ToolExecutionUpdateEvent │ │ └── ToolExecutionUpdateEvent │
└─────────────────────────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────────────────┐
│ Usage & ModelCost │ │ Usage & ModelCost │
│ Usage: input, output, cache_read, cache_write, total_tokens, cost │ │ Usage: input, output, cache_read, cache_write, total_tokens, cost │
│ ModelCost: input, output, cache_read, cache_write (all Float64) │ │ ModelCost: input, output, cache_read, cache_write (all Float64) │
└─────────────────────────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────────────────┐
│ Model │ │ Model │
│ - id, name, api, provider, base_url, reasoning: Bool │ │ - id, name, api, provider, base_url, reasoning: Bool │
│ - input: Vector{String} │ │ - input: Vector{String} │
│ - cost: ModelCost │ │ - cost: ModelCost │
│ - context_window, max_tokens: Int64 │ │ - context_window, max_tokens: Int64 │
└─────────────────────────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────────────────────┘
``` ```
learning/05-SESSION_MANAGEMENT.md
+13 -13
View File
@@ -9,23 +9,23 @@
┌─────────────────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────────────────┐
│ Session = Tree of Entries │ │ Session = Tree of Entries │
│ │ │ │
│ Each entry represents a change in conversation state │ │ Each entry represents a change in conversation state │
│ │ │ │
│ Branch Navigation: │ │ Branch Navigation: │
│ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │ │ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │
│ │ E1 │────▶│ E2 │────▶│ E3 │────▶│ E4 │────▶│ E5 │ (current leaf) │ │ │ E1 │────▶│ E2 │────▶│ E3 │────▶│ E4 │────▶│ E5 │ (current leaf) │
│ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ │ │ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ │
│ │ │ │ │ │ │ │ │ │ │ │ │ │
│ ▼ ▼ ▼ ▼ ▼ │ │ ▼ ▼ ▼ ▼ ▼ │
│ Message Message Compaction Message BranchSummary │ │ Message Message Compaction Message BranchSummary │
│ │ │ │
│ To navigate to E2 (fork point): │ │ To navigate to E2 (fork point): │
│ Session.moveTo(E2) │ │ Session.moveTo(E2) │
│ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │ │ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │
│ │ E1 │────▶│ E2 │────▶│ E3' │────▶│ E4' │────▶│ E5' │ (new branch) │ │ │ E1 │────▶│ E2 │────▶│ E3' │────▶│ E4' │────▶│ E5' │ (new branch) │
│ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ │ │ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ │
│ │ │ │ │ │ │ │
│ │ ▼ create BranchSummary │ │ │ ▼ create BranchSummary │
│ │ ┌─────┐ │ │ │ ┌─────┐ │
│ └──────│ E6 │ (branch summary) │ │ └──────│ E6 │ (branch summary) │
learning/06-TOOLS.md
+12 -12
View File
@@ -8,14 +8,14 @@
└─────────────────────────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────────────────┐
│ AgentTool │ │ AgentTool │
│ - name: String (identifier) │ │ - name: String (identifier) │
│ - label: String (display name) │ │ - label: String (display name) │
│ - description: String (what it does) │ │ - description: String (what it does) │
│ - parameters: JSON schema │ │ - parameters: JSON schema │
│ - execute::Function (main logic) │ │ - execute::Function (main logic) │
│ - prepare_arguments::Union{Function, Nothing} │ │ - prepare_arguments::Union{Function, Nothing} │
│ - execution_mode::Union{ToolExecutionMode, Nothing} │ │ - execution_mode::Union{ToolExecutionMode, Nothing} │
└─────────────────────────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────────────────────┘
│ │
┌───────────────┼───────────────┐ ┌───────────────┼───────────────┐
@@ -47,8 +47,8 @@
▼ ▼
┌────────────────────────────────────────────────────────┐ ┌────────────────────────────────────────────────────────┐
│ AgentLoop.executeToolCalls() │ │ AgentLoop.executeToolCalls() │
│ - Extract ToolCalls from message content │ │ - Extract ToolCalls from message content │
│ - Determine execution mode (sequential/parallel) │ │ - Determine execution mode (sequential/parallel) │
└────────────────────────────────────────────────────────┘ └────────────────────────────────────────────────────────┘
│ │
├─► executeToolCallsSequential() ├─► executeToolCallsSequential()
@@ -77,7 +77,7 @@
▼ ▼
┌────────────────────────────────────────────────────────┐ ┌────────────────────────────────────────────────────────┐
│ ToolResultMessage │ │ ToolResultMessage │
│ - tool_call_id: "ref to original ToolCall" │ │ - tool_call_id: "ref to original ToolCall" │
│ - tool_name: "bash" │ │ - tool_name: "bash" │
│ - content: [TextContent("file1.md\nfile2.md\n")] │ │ - content: [TextContent("file1.md\nfile2.md\n")] │
│ - is_error: false │ │ - is_error: false │
@@ -85,7 +85,7 @@
│ │
▼ ▼
┌────────────────────────────────────────────────────────┐ ┌────────────────────────────────────────────────────────┐
│ AgentState.messages.append(tool_result) │ │ AgentState.messages.append(tool_result) │
│ - Next turn: LLM sees tool results │ │ - Next turn: LLM sees tool results │
└────────────────────────────────────────────────────────┘ └────────────────────────────────────────────────────────┘
``` ```
learning/07-AGENTHARNESS.md
+16 -16
View File
@@ -9,31 +9,31 @@
┌─────────────────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────────────────┐
│ AgentHarness = Agent + Session + Resources │ │ AgentHarness = Agent + Session + Resources │
│ │ │ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │ │ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ AgentHarness │ │ │ │ AgentHarness │ │
│ │ - Manages Agent instances │ │ │ │ - Manages Agent instances │ │
│ │ - Provides Session persistence │ │ │ │ - Provides Session persistence │ │
│ │ - Manages resources (skills, prompt templates) │ │ │ │ - Manages resources (skills, prompt templates) │ │
│ │ - Handles extension hooks │ │ │ │ - Handles extension hooks │ │
│ │ - Coordinates tool execution with context │ │ │ │ - Coordinates tool execution with context │ │
│ └───────────────────────────────────────────────────────────────────────┘ │ │ └───────────────────────────────────────────────────────────────────────┘ │
│ │ │ │ │ │
│ ┌─────────────────────┼─────────────────────┐ │ │ ┌─────────────────────┼─────────────────────┐ │
│ ▼ ▼ ▼ │ │ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Agent │ │ SessionRepo │ │ Resources │ │ │ │ Agent │ │ SessionRepo │ │ Resources │ │
│ │ (state, │ │ (create, │ │ (skills, │ │ │ │ (state, │ │ (create, │ │ (skills, │ │
│ │ events) │ │ open, │ │ templates) │ │ │ │ events) │ │ open, │ │ templates) │ │
│ └──────────────┘ │ list) │ └──────────────┘ │ │ └──────────────┘ │ list) │ └──────────────┘ │
│ └──────────────┘ │ │ └──────────────┘ │
│ │ │ │ │ │
│ ▼ │ │ ▼ │
│ ┌──────────────┐ │ │ ┌──────────────┐ │
│ │ Session │ │ │ │ Session │ │
│ │ (history, │ │ │ │ (history, │ │
│ │ branching) │ │ │ │ branching) │ │
│ └──────────────┘ │ │ └──────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────────────────┐