update
This commit is contained in:
+84
-53
@@ -1,6 +1,6 @@
|
||||
# AgentCore.jl - Tools Deep Dive
|
||||
|
||||
## Tool Architecture
|
||||
## Tool Architecture with Data Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
@@ -12,7 +12,7 @@
|
||||
│ - name: String (identifier) │
|
||||
│ - label: String (display name) │
|
||||
│ - description: String (what it does) │
|
||||
│ - parameters: JSON schema │
|
||||
│ - parameters::Any (JSON schema or type) │
|
||||
│ - execute::Function (main logic) │
|
||||
│ - prepare_arguments::Union{Function, Nothing} │
|
||||
│ - execution_mode::Union{ToolExecutionMode, Nothing} │
|
||||
@@ -21,77 +21,108 @@
|
||||
┌───────────────┼───────────────┐
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||||
│ BashTool │ │ ReadTool │ │ WriteTool │
|
||||
│ - bash() │ │ - read() │ │ - write() │
|
||||
└─────────────┘ └─────────────┘ └─────────────┘
|
||||
┌─────────────┐
|
||||
│ EditTool │
|
||||
│ - edit() │
|
||||
└─────────────┘
|
||||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||||
│ BashTool │ │ ReadTool │ │ WriteTool │
|
||||
│ - bash() │ │ - read() │ │ - write() │
|
||||
└─────────────┘ └─────────────┘ └─────────────┘
|
||||
┌─────────────┐
|
||||
│ EditTool │
|
||||
│ - edit() │
|
||||
└─────────────┘
|
||||
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Tool Execution Flow │
|
||||
│ Tool Execution Data Flow │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
|
||||
Assistant Message
|
||||
┌────────────────────────────────────────────────────────┐
|
||||
│ AssistantMessage: │
|
||||
│ content: [ │
|
||||
│ TextContent("I'll check the files..."), │
|
||||
│ ToolCall("bash", {command: "ls -la"}), │
|
||||
│ ToolCall("read", {path: "README.md"}) │
|
||||
│ ] │
|
||||
└────────────────────────────────────────────────────────┘
|
||||
Input: AssistantMessage (from LLM)
|
||||
content::Vector{MessageContent}
|
||||
└─ Contains: TextContent[] and ToolCall[]
|
||||
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
│ extract ToolCalls │
|
||||
│ filter(c -> c isa ToolCall, assistant_message.content) │
|
||||
└─────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌────────────────────────────────────────────────────────┐
|
||||
│ AgentLoop.executeToolCalls() │
|
||||
│ - Extract ToolCalls from message content │
|
||||
│ - Determine execution mode (sequential/parallel) │
|
||||
└────────────────────────────────────────────────────────┘
|
||||
│
|
||||
├─► executeToolCallsSequential()
|
||||
│ (for tools that require order)
|
||||
│
|
||||
└─► executeToolCallsParallel()
|
||||
(for independent tools)
|
||||
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
│ ToolCall Type │
|
||||
│ • type::String ("tool") │
|
||||
│ • id::String (unique identifier) │
|
||||
│ • name::String (tool name to execute) │
|
||||
│ • arguments::Dict{String, Any} (JSON-like arguments) │
|
||||
│ • partial_json::Union{String, Nothing} │
|
||||
└─────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
├─► prepareToolCall()
|
||||
│ - before_tool_call hook (optional)
|
||||
│ - validate arguments
|
||||
│ - prepare arguments (optional)
|
||||
│ Input: tool_call::ToolCall
|
||||
│ Output: Union{PreparedToolCall, ImmediateToolCallOutcome}
|
||||
│
|
||||
├─► execute()
|
||||
│ - Tool-specific logic
|
||||
│ - Return AgentToolResult
|
||||
│ Steps:
|
||||
│ 1. Find tool by name in context.tools
|
||||
│ 2. before_tool_call hook (optional)
|
||||
│ Input: BeforeToolCallContext
|
||||
│ Output: BeforeToolCallResult (block, reason)
|
||||
│ 3. prepareToolCallArguments() (optional)
|
||||
│ Input: tool_call.arguments::Dict{String, Any}
|
||||
│ Output: prepared_arguments::Any
|
||||
│ 4. validateToolArguments()
|
||||
│ Input: prepared_tool_call.arguments
|
||||
│ Output: validated_args::Any
|
||||
│ 5. Return: PreparedToolCall(kind, tool_call, tool, args)
|
||||
│
|
||||
├─► executePreparedToolCall() (if prepared)
|
||||
│ Input: PreparedToolCall
|
||||
│ Output: ExecutedToolCallOutcome
|
||||
│
|
||||
│ tool.execute(tool_call.id, args, signal, on_update)
|
||||
│ Input: tool_call_id::String
|
||||
│ args::Any
|
||||
│ signal::Union{Any, Nothing}
|
||||
│ on_update::Function (streaming updates)
|
||||
│ Output: AgentToolResultMutable
|
||||
│ • content::Vector{MessageContent}
|
||||
│ • details::Any
|
||||
│ • usage::Union{Usage, Nothing}
|
||||
│ • terminate::Union{Bool, Nothing}
|
||||
│
|
||||
├─► finalizeExecutedToolCall()
|
||||
│ - after_tool_call hook (optional)
|
||||
│ Input: ExecutedToolCallOutcome
|
||||
│ Output: FinalizedToolCallOutcome
|
||||
│
|
||||
│ Steps:
|
||||
│ 1. after_tool_call hook (optional)
|
||||
│ Input: AfterToolCallContext
|
||||
│ Output: AfterToolCallResult (patches)
|
||||
│ 2. Apply patches to result
|
||||
│ 3. Return: FinalizedToolCallOutcome(tool_call, result, is_error)
|
||||
│
|
||||
└─► createToolResultMessage()
|
||||
- Emit ToolResultMessage
|
||||
|
||||
Input: FinalizedToolCallOutcome
|
||||
Output: ToolResultMessage
|
||||
• role: "toolResult"
|
||||
• tool_call_id::String (matches ToolCall.id)
|
||||
• tool_name::String (matches ToolCall.name)
|
||||
• content::Vector{MessageContent}
|
||||
• details::Any
|
||||
• usage::Union{Usage, Nothing}
|
||||
• added_tool_names::Union{Vector{String}, Nothing}
|
||||
• is_error::Bool
|
||||
• timestamp::Timestamp (Int64)
|
||||
│
|
||||
▼
|
||||
┌────────────────────────────────────────────────────────┐
|
||||
│ ToolResultMessage │
|
||||
│ - tool_call_id: "ref to original ToolCall" │
|
||||
│ - tool_name: "bash" │
|
||||
│ - content: [TextContent("file1.md\nfile2.md\n")] │
|
||||
│ - is_error: false │
|
||||
└────────────────────────────────────────────────────────┘
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
│ ToolResultMessage[] (one per ToolCall) │
|
||||
└─────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌────────────────────────────────────────────────────────┐
|
||||
│ AgentState.messages.append(tool_result) │
|
||||
│ - Next turn: LLM sees tool results │
|
||||
└────────────────────────────────────────────────────────┘
|
||||
├─► Append to context.messages (AgentState.messages)
|
||||
└─► Next turn: LLM sees tool results as input
|
||||
```
|
||||
|
||||
## Built-in Tools
|
||||
|
||||
## Built-in Tools
|
||||
|
||||
### 1. BashTool
|
||||
|
||||
```julia
|
||||
|
||||
Reference in New Issue
Block a user