update

src/tools/README.md

@@ -6,7 +6,7 @@ This document describes the complete tool lifecycle in the YiemAgent framework,
 
 ## Table of Contents
 
-1. [Quick Start: Four-Step Tool Lifecycle](#1-quick-start-four-step-tool-lifecycle)
+1. [Quick Start: Tool Lifecycle](#1-quick-start-tool-lifecycle)
 2. [Overview](#2-overview)
 3. [Tool Definition — The `agentTool` Struct](#3-tool-definition--the-agenttool-struct)
 4. [Tool Registration — Per-Agent Tool Stores](#4-tool-registration--per-agent-tool-stores)
@@ -27,9 +27,9 @@ This document describes the complete tool lifecycle in the YiemAgent framework,
 
 ---
 
-## 1. Quick Start: Four-Step Tool Lifecycle
+## 1. Quick Start: Tool Lifecycle
 
-This section shows the complete lifecycle from discovery to result extraction. Each step maps to the detailed sections below.
+This section shows the complete lifecycle from tool registration through execution and result extraction. Each step maps to the detailed sections below.
 
 ### Step 1: Discover — `listTools`
 
@@ -77,6 +77,61 @@ clearTools(store)  # Clear all tools from store
 
 ---
 
+### Step 2.5: Create Agent with Tools
+
+Wire the loaded tools into a new `yiemAgent` instance. The `tools` parameter is deep-copied into `agent._state.tools`; `_tool_store` is kept for runtime registration.
+
+```julia
+using YiemAgent, YiemAgent.type, YiemAgent.toolRegistry
+
+# 1. Set up ToolStore and load tools
+store = ToolStore(name="myAgent")
+loadTools(store, "src/tools")
+
+# 2. Create agent — pass tools + _tool_store
+agent = yiemAgent(
+    systemPrompt = "You are a helpful assistant.",
+    model = my_model,
+    tools = getTools(store),          # OrderedDict{String, agentTool}
+    llmCall = my_llm_call,            # Function that calls the LLM API
+    agentEventSink = my_event_sink,   # Function for TUI/logging
+    _tool_store = store,              # For runtime registerTool() calls
+)
+```
+
+**Manual registration** (without `loadTools`):
+
+```julia
+store = ToolStore(name="myAgent")
+registerTool(store, getTime_tool)
+registerTool(store, getWeather_tool)
+
+agent = yiemAgent(
+    tools = getTools(store),
+    llmCall = my_llm_call,
+    agentEventSink = my_event_sink,
+    _tool_store = store,
+)
+```
+
+**Key constructor parameters:**
+
+| Parameter | Type | Required | Purpose |
+|-----------|------|----------|---------|
+| `systemPrompt` | `String` | No (default: "You are helpful assistant.") | System prompt text |
+| `model` | `llmModel` | No | LLM model config |
+| `tools` | `OrderedDict{String, agentTool}` | No | Available tools (deep-copied) |
+| `messages` | `Vector{agentMessage}` | No (default: empty) | Initial conversation history |
+| `llmCall` | `Function` | **Yes** | `(messages::Dict) -> assistantMessage` — invokes the LLM |
+| `agentEventSink` | `Function` | **Yes** | `(event) -> nothing` — receives tool lifecycle events |
+| `_tool_store` | `ToolStore` | No | Runtime tool registry for `registerTool()` |
+
+Optional hooks: `prepareContext`, `formatMsgForLLM`, `beforeToolCall`, `afterToolCall`, `sessionId`, `maxRetryDelayMs`, `parallelToolExecute`.
+
+**Source:** `type.jl:609-657`, `toolRegistry.jl:38-40, 191-195`
+
+---
+
 ### Step 3: Use — Tool Execution
 
 Tools can be used in two ways: