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