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-08-05 19:09:56 +07:00
parent afc866a3a5
commit ec28e0ff54
3 changed files with 953 additions and 594 deletions
Download Patch File Download Diff File Expand all files Collapse all files
etc.jl
-594
View File
@@ -1,596 +1,2 @@
# ── executeToolCalls() Julia pseudo code ──────────────────────────
# Full call stack from runLoop → executeToolCalls → prepare → execute → finalize → emit
"""
preparedToolCall(tool, toolCall, args)
Intermediate state between tool call validation and execution.
This struct is created after `prepareToolCall` succeeds and serves
as the bridge to the execution phase. Keeping the resolved tool,
original call metadata, and validated args together avoids repeated
lookups and allows the execution phase to access all necessary data
without carrying the full context through the call chain.
"""
struct preparedToolCall
tool::agentTool # The resolved tool definition from the context
toolCall::agentToolCall # The original tool call from the assistant
args::any # Validated (and coerced) argument values
end
"""
immediateOutcome(result, isError)
A tool call that was resolved without actual execution — either
because the tool was not found, validation failed, or a
`beforeToolCall` hook blocked the call. The result is produced
immediately and emitted as a tool result message.
Returning an outcome instead of throwing an exception is intentional:
it lets the agent feed the error back to the LLM as a tool result so
the model can recover — for example, by re-issuing a tool call with
corrected arguments after a validation failure.
"""
struct immediateOutcome
result::agentToolResult # The pre-computed tool result
isError::bool # Whether this outcome represents an error
end
"""
executedOutcome(result, isError)
A tool call that has been executed by `tool.execute()` but has not
yet been through the `afterToolCall` hook. This intermediate state
is necessary because the hook may mutate the result (content, usage,
termination, error status). Keeping execution and finalization separate
allows the hook to inspect the raw result and decide whether to
transform it or replace it entirely.
"""
struct executedOutcome
result::agentToolResult # The tool's execution result
isError::bool # Whether execution raised an error
end
"""
finalizedOutcome(toolCall, result, isError)
The complete outcome of a tool call after both execution and the
`afterToolCall` hook. This is the final form that is used to
construct the `toolResultMessage` emitted to the agent loop.
The three-phase design (prepare → execute → finalize) exists so that
each phase has a single responsibility: preparation handles validation
and gating, execution performs the actual work, and finalization
applies post-processing hooks. This separation allows the agent loop
to emit `tool_execution_end` events with the finalized data while
keeping each phase independently testable and swappable.
"""
struct finalizedOutcome
toolCall::agentToolCall # The original tool call reference
result::agentToolResult # The final tool result (post-afterToolCall)
isError::bool # Whether the call failed or was blocked
end
"""
ToolCallBatch(messages, terminate)
A batch of tool result messages from executing one or more tool calls.
The `terminate` flag indicates whether all tools in the batch requested
termination, which causes the agent loop to stop processing further turns.
This flag is set by the tool implementation (not the end user) to signal
that the agent should not call the LLM again. Typical use cases:
- Task completion: a tool like `deploy` or `submit` finishes its work and
returns `terminate: true` so the agent stops instead of asking the LLM
what to do next.
- Unrecoverable error: a tool hits a fatal condition (e.g. database
connection lost, auth token expired) and returns `terminate: true` so
the agent stops with an error message rather than retrying.
- Async handoff: a tool triggers a long-running external operation and
wants the agent to stop now; the external system will later resume the
agent via `continue()`.
If `terminate` is `false` (default), the agent loop feeds the tool results
back to the LLM for another turn.
"""
struct toolCallBatch
messages::vector{toolResultMessage} # Tool result messages for this batch
terminate::bool # Whether the batch should terminate the loop
end
"""
createErrorToolResult(msg)
Builds an `agentToolResult` containing a single text content item
with the provided error message and an empty details dictionary.
Used when a tool call cannot be executed due to errors.
Returning a result instead of throwing ensures that errors at any
point in the tool call pipeline are fed back to the LLM as a tool
result message. This allows the model to see the error and decide
whether to retry, re-issue the call with different arguments, or
report failure to the user.
"""
function createErrorToolResult(msg::String)::agentToolResult
return agentToolResult([textContent("text", msg)], dict{any,any}())
end
"""
createToolResultMessage(f)
Constructs a `toolResultMessage` from a `finalizedOutcome`.
Normalizes missing content to an empty array and includes
the `addedToolNames` field only when the tool dynamically
registered new tools during execution.
This conversion is necessary because the tool result is an
`agentToolResult` used by tool implementations, while the agent
loop consumes `toolResultMessage` objects that become part of the
conversation history. The message format includes metadata like
timestamp and tool call ID that the raw result does not carry,
and it is the object emitted via `message_start`/`message_end`
events so the LLM receives the result as a proper assistant/user
message in the context window.
"""
function createToolResultMessage(f::finalizedOutcome)::toolResultMessage
return toolResultMessage(
"toolResult", f.toolCall.id, f.toolCall.name,
f.result.content, f.result.details, f.result.usage,
get(f.result, :addedToolNames, string[]), f.isError, nowMillis()
)
end
"""
shouldTerminate(finalizedCalls)
Returns `true` only when every finalized call in the batch has
`result.terminate == true`. All tools must agree — if any tool
did not request termination, the agent continues. This prevents
a single tool that happens to set `terminate: true` (e.g. for
metadata purposes) from accidentally stopping the agent when
other tools in the batch did not intend to terminate.
"""
function shouldTerminate(batches::vector{finalizedOutcome})::bool
return !isempty(batches) && all(b -> b.result.terminate, batches)
end
"""
prepareToolCallArguments(tool, toolCall)
Calls the tool's optional `prepareArguments` hook to transform
the raw argument values from the LLM before schema validation.
If the tool has no hook or the hook returns the same object
reference, the original call is returned unchanged.
This hook allows tools to normalize arguments that the LLM may
have produced in a non-standard format — for example, converting
a date string to a timestamp, expanding a short file path to an
absolute path, or normalizing casing. It runs before schema
validation so the validator sees the normalized form rather than
raw LLM output.
"""
function prepareToolCallArguments(tool::agentTool, toolCall::agentToolCall)::agentToolCall
if tool.prepareArguments === nothing
return toolCall
end
prepared = tool.prepareArguments(toolCall.arguments)
if prepared == toolCall.arguments
return toolCall
end
return merge(toolCall, dict(:arguments => prepared))
end
"""
prepareToolCall(context, assistantMsg, toolCall, config, signal)
Resolves the tool by name, prepares and validates its arguments,
and runs the `beforeToolCall` hook. Returns a `preparedToolCall`
if successful or an `immediateOutcome` if the tool is not found,
validation fails, the hook blocks execution, or the signal is
aborted. Errors during preparation are caught and returned as
immediate error outcomes so the agent loop can feed them back
to the model.
The key design decision here is that preparation never throws.
Every failure path returns an `immediateOutcome` with an error
result. This ensures the agent loop always receives a valid tool
result message for every tool call the assistant requested,
regardless of whether preparation succeeded. The LLM can then
use the error message to decide whether to retry with different
arguments or acknowledge the failure.
"""
function prepareToolCall(
context::agentContext,
assistantMsg::assistantMessage,
toolCall::agentToolCall,
config::agentLoopConfig,
signal::union{nothing,abortSignal},
)::union{preparedToolCall,immediateOutcome}
tool = find(t -> t.name == toolCall.name, context.tools)
if tool === nothing
return immediateOutcome(createErrorToolResult("Tool $toolCall.name not found"), true)
end
try
# 1. prepare arguments (tool-specific transform)
prepared = prepareToolCallArguments(tool, toolCall)
validatedArgs = validateToolArguments(tool, prepared)
# 2. beforeToolCall hook — can block
if config.beforeToolCall !== nothing
before = config.beforeToolCall(
assistantMsgCtx(assistantMsg, toolCall, validatedArgs, context), signal
)
if signal !== nothing && signal.aborted
return immediateOutcome(createErrorToolResult("Operation aborted"), true)
end
if before !== nothing && before.block
return immediateOutcome(
createErrorToolResult(get(before, :reason, "Tool execution was blocked")), true)
end
end
return preparedToolCall(tool, toolCall, validatedArgs)
catch err
return immediateOutcome(createErrorToolResult(sprint(showerror, err)), true)
end
end
# ── per-call execution ──────────────────────────────────────────
"""
executePreparedToolCall(prep, signal, emit)
Executes the tool by calling `tool.execute()` with the validated
arguments, the abort signal, and a callback for streaming partial
results. Emits `toolExecutionUpdate` events for each partial
result batch. Waits for all pending update events to settle before
returning. Catches execution errors and returns them as an error
outcome. The `accepting` guard prevents emitting updates after
the call has finished.
Long-running tools (e.g. file uploads, model training, web scraping)
may take seconds or minutes. The streaming update mechanism allows
UI listeners and other consumers to show progress in real time rather
than waiting for the entire call to complete. The `accepting` guard
ensures that if the tool's execute function yields after emitting
updates but before returning, no duplicate or stale updates are
emitted after the result has already been captured.
"""
function executePreparedToolCall(
prep::preparedToolCall,
signal::union{nothing,abortSignal},
emit::agentEventSink,
)::executedOutcome
updateEvents = promise[]
accepting = true
try
result = prep.tool.execute(
prep.toolCall.id, prep.args, signal,
partialResult -> begin
if accepting
push!(updateEvents,
emit(toolExecUpdateEvent(prep.toolCall.id, prep.toolCall.name,
prep.toolCall.arguments, partialResult)))
end
end
)
accepting = false
wait.(updateEvents)
return executedOutcome(result, false)
catch err
accepting = false
wait.(updateEvents)
return executedOutcome(createErrorToolResult(sprint(showerror, err)), true)
end
end
# ── per-call finalization ───────────────────────────────────────
"""
finalizeExecutedToolCall(context, assistantMsg, prep, executed, config, signal)
Runs the `afterToolCall` hook on the executed result, allowing
the consumer to mutate the result content, details, usage,
termination flag, or error status. Catches errors from the
hook and converts them to error outcomes. Returns a
`finalizedOutcome` that is used to construct the tool result
message.
The `afterToolCall` hook exists as a post-processing step that
runs after every tool call regardless of success or failure.
Common use cases include:
- Masking sensitive data from result content before the LLM
sees it (e.g. removing API keys from error messages).
- Normalizing usage tracking data into a consistent format.
- Inspecting the result and deciding to flip `terminate: true`
based on business logic (e.g. "if deployment failed, stop
the agent rather than retrying").
- Wrapping an error result in a friendlier message for the LLM
to understand.
If the hook itself throws, the error is caught and the result
becomes an error outcome. This ensures the tool pipeline never
breaks due to a buggy hook.
"""
function finalizeExecutedToolCall(
context::agentContext,
assistantMsg::assistantMessage,
prep::preparedToolCall,
executed::executedOutcome,
config::agentLoopConfig,
signal::union{nothing,abortSignal},
)::finalizedOutcome
result = executed.result
isError = executed.isError
if config.afterToolCall !== nothing
try
after = config.afterToolCall(
afterCtx(assistantMsg, prep.toolCall, prep.args, result, isError, context), signal
)
if after !== nothing
result = merge(result, dict(:content=>get(after,:content,result.content),
:details=>get(after,:details,result.details),
:usage=>get(after,:usage,result.usage),
:terminate=>get(after,:terminate,result.terminate)))
isError = get(after, :isError, isError)
end
catch err
result = createErrorToolResult(sprint(showerror, err))
isError = true
end
end
return finalizedOutcome(prep.toolCall, result, isError)
end
"""
emitToolExecutionEnd(finalized, emit)
Emits the `toolExecutionEnd` event with the finalized outcome,
signalling to listeners that the tool call has completed.
This event is part of the tool execution lifecycle:
`tool_execution_start` → (zero or more `tool_execution_update` events) →
`tool_execution_end`. Listeners (such as the TUI or logging systems)
use this lifecycle to track individual tool calls. The event carries
the final result so listeners have all the data they need without
requiring external state lookups.
"""
function emitToolExecutionEnd(finalized::finalizedOutcome, emit::agentEventSink)
emit(toolExecEndEvent(finalized.toolCall.id, finalized.toolCall.name,
finalized.result, finalized.isError))
end
# ── sequential execution ────────────────────────────────────────
"""
executeToolCallsSequential(context, assistantMsg, toolCalls, config, signal, emit)
Executes tool calls one at a time in the order they appear. For each
call: emits `toolExecutionStart`, runs `prepareToolCall`,
then either resolves the immediate outcome or executes/finalizes
the prepared call. Emits `toolExecutionEnd` and creates the tool
result message before proceeding to the next call. Respects the
abort signal — if aborted, remaining calls are skipped. Returns
a batch with `terminate` determined by whether all results set
the termination flag.
Sequential execution is required when tool calls have implicit
dependencies — for example, a `create_database` tool must complete
before `create_table` can reference it. It is also the safer
default because it prevents race conditions when multiple tools
share state (e.g. writing to the same file or API rate limits).
Use parallel only when you are confident the tools are independent.
"""
function executeToolCallsSequential(
context::agentContext,
assistantMsg::assistantMessage,
toolCalls::vector{agentToolCall},
config::agentLoopConfig,
signal::union{nothing,abortSignal},
emit::agentEventSink,
)::agentToolCallBatch
finalizedCalls = finalizedOutcome[]
messages = toolResultMessage[]
for tc in toolCalls
emit(toolExecStartEvent(tc.id, tc.name, tc.arguments))
prep = prepareToolCall(context, assistantMsg, tc, config, signal)
if prep isa immediateOutcome
finalized = finalizedOutcome(tc, prep.result, prep.isError)
else
executed = executePreparedToolCall(prep, signal, emit)
finalized = finalizeExecutedToolCall(context, assistantMsg, prep, executed, config, signal)
end
emitToolExecutionEnd(finalized, emit)
push!(messages, createToolResultMessage(finalized))
push!(finalizedCalls, finalized)
if signal !== nothing && signal.aborted
break
end
end
return toolCallBatch(messages, shouldTerminate(finalizedCalls))
end
# ── parallel execution ──────────────────────────────────────────
"""
executeToolCallsParallel(context, assistantMsg, toolCalls, config, signal, emit)
Prepares all tool calls concurrently and spawns a task for each
prepared call. Immediate outcomes are resolved instantly. Task
entries are collected in order, then `fetch`ed to await all
concurrent executions. Tool result messages are created from
finalized outcomes in order and returned as a batch. Respects
the abort signal — if aborted during preparation, remaining
calls are skipped. Finalization order preserves the original
call order.
Parallel execution is appropriate when the assistant requests
independent tools — for example, reading multiple files, querying
separate databases, or making independent API calls. It reduces
wall-clock time compared to sequential execution. The tradeoff is
that parallel calls can overwhelm external resources (rate limits,
connection pools, disk I/O). Finalization preserves the original
call order so tool result messages appear in the same order the
assistant requested them, regardless of which call finishes first.
"""
function executeToolCallsParallel(
context::agentContext,
assistantMsg::assistantMessage,
toolCalls::vector{agentToolCall},
config::agentLoopConfig,
signal::union{nothing,abortSignal},
emit::agentEventSink,
)::agentToolCallBatch
entries = union{finalizedOutcome,task{finalizedOutcome}}[]
for tc in toolCalls
emit(toolExecStartEvent(tc.id, tc.name, tc.arguments))
prep = prepareToolCall(context, assistantMsg, tc, config, signal)
if prep isa immediateOutcome
finalized = finalizedOutcome(tc, prep.result, prep.isError)
emitToolExecutionEnd(finalized, emit)
push!(entries, finalized)
else
task = task() do
executed = executePreparedToolCall(prep, signal, emit)
finalized = finalizeExecutedToolCall(context, assistantMsg, prep, executed, config, signal)
emitToolExecutionEnd(finalized, emit)
return finalized
end
schedule(task)
push!(entries, task)
end
if signal !== nothing && signal.aborted
break
end
end
finalizedCalls = finalizedOutcome[]
for entry in entries
outcome = entry isa task ? fetch(entry) : entry
push!(finalizedCalls, outcome)
end
messages = toolResultMessage[]
for f in finalizedCalls
push!(messages, createToolResultMessage(f))
end
return toolCallBatch(messages, shouldTerminate(finalizedCalls))
end
"""
executeToolCalls(context, assistantMsg, toolCalls, config, signal, emit)
Dispatches to sequential or parallel execution. Uses sequential mode
when `config.toolExecution == "sequential"` or when any of the
tool calls reference a tool with `executionMode: "sequential"`.
Otherwise uses parallel execution. This is the entry point called
from `streamAssistantResponse` in the agent loop.
The sequential mode takes priority over parallel because it is the
safe default. If even one tool in a batch is marked sequential, all
tools execute sequentially — this prevents a single dependent tool
from racing with an otherwise independent one. The per-tool
`executionMode` allows fine-grained control (e.g. most tools are
parallel but a specific write tool is sequential), while the config-level
`toolExecution` provides a global override.
"""
function executeToolCalls(
context::agentContext,
assistantMsg::assistantMessage,
toolCalls::vector{agentToolCall},
config::agentLoopConfig,
signal::union{nothing,abortSignal},
emit::agentEventSink,
)::agentToolCallBatch
hasSequential = any(tc ->
any(t -> t.name == tc.name && get(t.executionMode, "parallel") == "sequential",
context.tools), toolCalls)
if config.toolExecution == "sequential" || hasSequential
return executeToolCallsSequential(context, assistantMsg, toolCalls, config, signal, emit)
else
return executeToolCallsParallel(context, assistantMsg, toolCalls, config, signal, emit)
end
end
src/agentCore.jl
+765
View File
@@ -213,6 +213,771 @@ function _process_message(agent::yiemAgent, msg)::assistantMessage
end
"""
executeToolCalls(context, assistantMsg, toolCalls, config, signal, emit)
Dispatches to sequential or parallel execution. Uses sequential mode
when `config.toolExecution == "sequential"` or when any of the
tool calls reference a tool with `executionMode: "sequential"`.
Otherwise uses parallel execution. This is the entry point called
from `streamAssistantResponse` in the agent loop.
The sequential mode takes priority over parallel because it is the
safe default. If even one tool in a batch is marked sequential, all
tools execute sequentially — this prevents a single dependent tool
from racing with an otherwise independent one. The per-tool
`executionMode` allows fine-grained control (e.g. most tools are
parallel but a specific write tool is sequential), while the config-level
`toolExecution` provides a global override.
"""
function executeToolCalls(
context::agentContext,
assistantMsg::assistantMessage,
toolCalls::vector{agentToolCall},
config::agentLoopConfig,
signal::union{nothing,abortSignal},
emit::Function,
)::agentToolCallBatch
hasSequential = false
for tc in toolCalls
for t in context.tools
if t.name == tc.name && get(t.executionMode, "parallel") == "sequential"
hasSequential = true
break
end
end
if hasSequential
break
end
end
if config.toolExecution == "sequential" || hasSequential
return executeToolCallsSequential(context, assistantMsg, toolCalls, config, signal, emit)
else
return executeToolCallsParallel(context, assistantMsg, toolCalls, config, signal, emit)
end
end
"""
createErrorToolResult(msg::String) -> agentToolResult
Builds an `agentToolResult` containing a single text content item
with the provided error message and an empty details dictionary.
Used when a tool call cannot be executed due to errors.
Returning a result instead of throwing ensures that errors at any
point in the tool call pipeline are fed back to the LLM as a tool
result message. This allows the model to see the error and decide
whether to retry, re-issue the call with different arguments, or
report failure to the user.
# Arguments
- `msg::String`: The error message to embed in the result
# Returns
- `agentToolResult`: A result with `content = [textContent("text", msg)]`
# Examples
```julia
julia> createErrorToolResult("Tool not found")
agentToolResult([textContent("text", "Tool not found")], Dict{Any,Any}())
```
"""
function createErrorToolResult(msg::String)::agentToolResult
return agentToolResult([textContent("text", msg)], dict{any,any}())
end
"""
createToolResultMessage(f::finalizedOutcome) -> toolResultMessage
Constructs a `toolResultMessage` from a `finalizedOutcome`.
Normalizes missing content to an empty array and includes the
`addedToolNames` field only when the tool dynamically registered
new tools during execution.
This conversion is necessary because the tool result is an
`agentToolResult` used by tool implementations, while the agent
loop consumes `toolResultMessage` objects that become part of the
conversation history. The message format includes metadata like
timestamp and tool call ID that the raw result does not carry, and
it is the object emitted via `messageStart`/`messageEnd` events
so the LLM receives the result as a proper assistant/user message
in the context window.
# Arguments
- `f::finalizedOutcome`: The finalized tool call outcome
# Returns
- `toolResultMessage`: A message ready for the agent loop context
# Examples
```julia
julia> outcome = finalizedOutcome(tc, agentToolResult(content, details, usage, false), false);
julia> createToolResultMessage(outcome)
toolResultMessage("toolResult", "call_1", "search_wine", content, details, usage, [], false, 1234567890)
```
"""
function createToolResultMessage(f::finalizedOutcome)::toolResultMessage
return toolResultMessage(
"toolResult", f.toolCall.id, f.toolCall.name,
f.result.content, f.result.details, f.result.usage,
get(f.result, :addedToolNames, string[]), f.isError, nowMillis()
)
end
"""
shouldTerminate(finalizedCalls::Vector{finalizedOutcome}) -> Bool
Returns `true` only when every finalized call in the batch has
`result.terminate == true`. All tools must agree — if any tool
did not request termination, the agent continues. This prevents
a single tool that happens to set `terminate: true` (e.g. for
metadata purposes) from accidentally stopping the agent when
other tools in the batch did not intend to terminate.
# Arguments
- `finalizedCalls`: Vector of finalized tool call outcomes
# Returns
- `Bool`: `true` if all calls requested termination
# Examples
```julia
julia> shouldTerminate(finalizedOutcome[])
false
julia> shouldTerminate([finalizedOutcome(tc, agentToolResult([], dict{any,any}(), dict{any,any}(), false), false) for _ in 1:2])
false
julia> shouldTerminate([finalizedOutcome(tc, agentToolResult([], dict{any,any}(), dict{any,any}(), true), false) for _ in 1:2])
true
```
"""
function shouldTerminate(batches::vector{finalizedOutcome})::bool
return !isempty(batches) && all(b -> b.result.terminate, batches)
end
"""
prepareToolCallArguments(tool::agentTool, toolCall::agentToolCall) -> agentToolCall
Calls the tool's optional `prepareArguments` hook to transform the
raw argument values from the LLM before schema validation. If the
tool has no hook or the hook returns the same object reference, the
original call is returned unchanged.
This hook allows tools to normalize arguments that the LLM may have
produced in a non-standard format — for example, converting a date
string to a timestamp, expanding a short file path to an absolute
path, or normalizing casing. It runs before schema validation so
the validator sees the normalized form rather than raw LLM output.
# Arguments
- `tool::agentTool`: The tool definition (may have a `prepareArguments` hook)
- `toolCall::agentToolCall`: The raw tool call from the assistant
# Returns
- `agentToolCall`: The tool call with potentially transformed arguments
# Examples
```julia
# No prepareArguments hook — returns input unchanged
prepareToolCallArguments(noHookTool, tc)
# => tc # same reference
# With hook that normalizes arguments
prepareToolCallArguments(normalizeTool, tc)
# => agentToolCall{..., arguments=Dict("date" => 1700000000)} # "2024-01-15" → timestamp
```
"""
function prepareToolCallArguments(tool::agentTool, toolCall::agentToolCall)::agentToolCall
if tool.prepareArguments === nothing
return toolCall
end
prepared = tool.prepareArguments(toolCall.arguments)
if prepared == toolCall.arguments
return toolCall
end
return merge(toolCall, dict(:arguments => prepared))
end
"""
prepareToolCall(context, assistantMsg, toolCall, config, signal) ->
Union{preparedToolCall,immediateOutcome}
Resolves the tool by name, prepares and validates its arguments,
and runs the `beforeToolCall` hook. Returns a `preparedToolCall`
if successful or an `immediateOutcome` if the tool is not found,
validation fails, the hook blocks execution, or the signal is
aborted. Errors during preparation are caught and returned as
immediate error outcomes so the agent loop can feed them back
to the model.
The key design decision here is that preparation never throws.
Every failure path returns an `immediateOutcome` with an error
result. This ensures the agent loop always receives a valid tool
result message for every tool call the assistant requested,
regardless of whether preparation succeeded. The LLM can then
use the error message to decide whether to retry with different
arguments or acknowledge the failure.
# Arguments
- `context::agentContext`: Current agent context with tools and messages
- `assistantMsg::assistantMessage`: The assistant message containing the tool call
- `toolCall::agentToolCall`: The tool call to prepare
- `config::agentLoopConfig`: Loop configuration (may include `beforeToolCall`)
- `signal::Union{Nothing,AbortSignal}`: Optional abort signal
# Returns
- `preparedToolCall`: If preparation succeeded (tool found, arguments valid, not blocked)
- `immediateOutcome`: If preparation failed (tool missing, invalid args, blocked, aborted)
# Notes
- Tool lookup is by name via `context.tools`
- Validation uses `validateToolArguments` which coerces types per the tool schema
- The `beforeToolCall` hook can block execution by returning `{ block: true }`
# Examples
```julia
# Success path
prepareToolCall(context, msg, tc, config, signal)
# => preparedToolCall(tool, tc, validatedArgs)
# Tool not found
prepareToolCall(context, msg, tcNoMatch, config, signal)
# => immediateOutcome(createErrorToolResult("Tool fake_tool not found"), true)
# Validation failure
prepareToolCall(context, msg, tcBadArgs, config, signal)
# => immediateOutcome(createErrorToolResult("Validation failed..."), true)
# Aborted during preparation
prepareToolCall(context, msg, tc, config, abortedSignal)
# => immediateOutcome(createErrorToolResult("Operation aborted"), true)
```
"""
function prepareToolCall(
context::agentContext,
assistantMsg::assistantMessage,
toolCall::agentToolCall,
config::agentLoopConfig,
signal::union{nothing,abortSignal},
)::union{preparedToolCall,immediateOutcome}
tool = find(t -> t.name == toolCall.name, context.tools)
if tool === nothing
return immediateOutcome(createErrorToolResult("Tool $toolCall.name not found"), true)
end
try
# 1. prepare arguments (tool-specific transform)
prepared = prepareToolCallArguments(tool, toolCall)
validatedArgs = validateToolArguments(tool, prepared)
# 2. beforeToolCall hook — can block
if config.beforeToolCall !== nothing
before = config.beforeToolCall(
assistantMsgCtx(assistantMsg, toolCall, validatedArgs, context), signal
)
if signal !== nothing && signal.aborted
return immediateOutcome(createErrorToolResult("Operation aborted"), true)
end
if before !== nothing && before.block
return immediateOutcome(
createErrorToolResult(get(before, :reason, "Tool execution was blocked")), true)
end
end
return preparedToolCall(tool, toolCall, validatedArgs)
catch err
return immediateOutcome(createErrorToolResult(sprint(showerror, err)), true)
end
end
# ── per-call execution ──────────────────────────────────────────
"""
executePreparedToolCall(prep, signal, emit) -> executedOutcome
Executes the tool by calling `tool.execute()` with the validated
arguments, the abort signal, and a callback for streaming partial
results. Emits `toolExecutionUpdate` events for each partial
result batch. Waits for all pending update events to settle before
returning. Catches execution errors and returns them as an error
outcome. The `accepting` guard prevents emitting updates after
the call has finished.
Long-running tools (e.g. file uploads, model training, web scraping)
may take seconds or minutes. The streaming update mechanism allows
UI listeners and other consumers to show progress in real time rather
than waiting for the entire call to complete. The `accepting` guard
ensures that if the tool's execute function yields after emitting
updates but before returning, no duplicate or stale updates are
emitted after the result has already been captured.
# Arguments
- `prep::preparedToolCall`: The prepared tool call (resolved tool + validated args)
- `signal::Union{Nothing,AbortSignal}`: Optional abort signal
- `emit::Function`: Event emitter for lifecycle events
# Returns
- `executedOutcome`: The execution result and whether it was an error
# Examples
```julia
# Successful execution
executePreparedToolCall(prep, nothing, emit)
# => executedOutcome(agentToolResult([textContent("text", "Found 3 wines")], dict{any,any}(), dict{any,any}()), false)
# Execution error
executePreparedToolCall(prep, nothing, emit)
# => executedOutcome(createErrorToolResult("Connection timeout"), true)
```
"""
function executePreparedToolCall(
prep::preparedToolCall,
signal::union{nothing,abortSignal},
emit::Function,
)::executedOutcome
updateEvents = promise[]
accepting = true
try
result = prep.tool.execute(
prep.toolCall.id, prep.args, signal,
partialResult -> begin
if accepting
push!(updateEvents,
emit(toolExecUpdateEvent(prep.toolCall.id, prep.toolCall.name,
prep.toolCall.arguments, partialResult)))
end
end
)
accepting = false
wait.(updateEvents)
return executedOutcome(result, false)
catch err
accepting = false
wait.(updateEvents)
return executedOutcome(createErrorToolResult(sprint(showerror, err)), true)
end
end
# ── per-call finalization ───────────────────────────────────────
"""
finalizeExecutedToolCall(context, assistantMsg, prep, executed, config, signal) ->
finalizedOutcome
Runs the `afterToolCall` hook on the executed result, allowing
the consumer to mutate the result content, details, usage,
termination flag, or error status. Catches errors from the
hook and converts them to error outcomes. Returns a
`finalizedOutcome` that is used to construct the tool result
message.
The `afterToolCall` hook exists as a post-processing step that
runs after every tool call regardless of success or failure.
Common use cases include:
- Masking sensitive data from result content before the LLM
sees it (e.g. removing API keys from error messages).
- Normalizing usage tracking data into a consistent format.
- Inspecting the result and deciding to flip `terminate: true`
based on business logic (e.g. "if deployment failed, stop
the agent rather than retrying").
- Wrapping an error result in a friendlier message for the LLM
to understand.
If the hook itself throws, the error is caught and the result
becomes an error outcome. This ensures the tool pipeline never
breaks due to a buggy hook.
# Arguments
- `context::agentContext`: Current agent context
- `assistantMsg::assistantMessage`: The assistant message that made the tool call
- `prep::preparedToolCall`: The originally prepared tool call
- `executed::executedOutcome`: The raw execution result
- `config::agentLoopConfig`: Loop configuration (may include `afterToolCall`)
- `signal::Union{Nothing,AbortSignal}`: Optional abort signal
# Returns
- `finalizedOutcome`: The finalized outcome ready for message construction
# Examples
```julia
# No afterToolCall hook — returns executed result unchanged
finalizeExecutedToolCall(context, msg, prep, execOk, config, nothing)
# => finalizedOutcome(tc, execOk.result, false)
# afterToolCall masks sensitive data
finalizeExecutedToolCall(context, msg, prep, execOk, configWithHook, nothing)
# => finalizedOutcome(tc, maskedResult, false)
# afterToolCall flips terminate based on business logic
finalizeExecutedToolCall(context, msg, prep, execFail, config, nothing)
# => finalizedOutcome(tc, {terminate: true}, true)
```
"""
function finalizeExecutedToolCall(
context::agentContext,
assistantMsg::assistantMessage,
prep::preparedToolCall,
executed::executedOutcome,
config::agentLoopConfig,
signal::union{nothing,abortSignal},
)::finalizedOutcome
result = executed.result
isError = executed.isError
if config.afterToolCall !== nothing
try
after = config.afterToolCall(
afterCtx(assistantMsg, prep.toolCall, prep.args, result, isError, context), signal
)
if after !== nothing
result = merge(result, dict(:content=>get(after,:content,result.content),
:details=>get(after,:details,result.details),
:usage=>get(after,:usage,result.usage),
:terminate=>get(after,:terminate,result.terminate)))
isError = get(after, :isError, isError)
end
catch err
result = createErrorToolResult(sprint(showerror, err))
isError = true
end
end
return finalizedOutcome(prep.toolCall, result, isError)
end
"""
emitToolExecutionEnd(finalized, emit)
Emits the `toolExecutionEnd` event with the finalized outcome,
signalling to listeners that the tool call has completed.
This event is part of the tool execution lifecycle:
`toolExecutionStart` → (zero or more `toolExecutionUpdate` events) →
`toolExecutionEnd`. Listeners (such as the TUI or logging systems)
use this lifecycle to track individual tool calls. The event carries
the final result so listeners have all the data they need without
requiring external state lookups.
# Arguments
- `finalized::finalizedOutcome`: The finalized outcome to report
- `emit::Function`: Event emitter
# Notes
- Part of a three-event lifecycle per tool call
- Carries the complete result so listeners need no external lookups
# Examples
```julia
# Emits a single event; returns nothing
emitToolExecutionEnd(finalized, emit)
# (emit receives toolExecEndEvent("call_1", "search_wine", result, false))
```
"""
function emitToolExecutionEnd(finalized::finalizedOutcome, emit::Function)
emit(toolExecEndEvent(finalized.toolCall.id, finalized.toolCall.name,
finalized.result, finalized.isError))
end
# ── sequential execution ────────────────────────────────────────
"""
executeToolCallsSequential(context, assistantMsg, toolCalls, config, signal, emit) ->
agentToolCallBatch
Executes tool calls one at a time in the order they appear. For each
call: emits `toolExecutionStart`, runs `prepareToolCall`,
then either resolves the immediate outcome or executes/finalizes
the prepared call. Emits `toolExecutionEnd` and creates the tool
result message before proceeding to the next call. Respects the
abort signal — if aborted, remaining calls are skipped. Returns
a batch with `terminate` determined by whether all results set
the termination flag.
Sequential execution is required when tool calls have implicit
dependencies — for example, a `create_database` tool must complete
before `create_table` can reference it. It is also the safer
default because it prevents race conditions when multiple tools
share state (e.g. writing to the same file or API rate limits).
Use parallel only when you are confident the tools are independent.
# Arguments
- `context::agentContext`: Current agent context
- `assistantMsg::assistantMessage`: The assistant message containing tool calls
- `toolCalls::Vector{agentToolCall}`: Tool calls to execute (ordered)
- `config::agentLoopConfig`: Loop configuration
- `signal::Union{Nothing,AbortSignal}`: Optional abort signal
- `emit::Function`: Event emitter
# Returns
- `agentToolCallBatch`: Result messages and termination flag
# Notes
- Calls execute strictly in order; each completes fully before the next begins
- Aborting during one call skips all remaining calls
- If any call returns `terminate: true`, it is included in the batch but does
not force termination unless all calls do
# Examples
```julia
# Two independent reads — both succeed
executeToolCallsSequential(ctx, msg, [readTc, readTc2], config, nothing, emit)
# => agentToolCallBatch([result1, result2], false)
# One tool fails, next is skipped due to abort
executeToolCallsSequential(ctx, msg, [tc1, tc2, tc3], config, abortedSignal, emit)
# => agentToolCallBatch([result1], false) # tc2 failed, tc3 skipped
# All tools request termination
executeToolCallsSequential(ctx, msg, [deployTc], config, nothing, emit)
# => agentToolCallBatch([deployResult], true)
```
"""
function executeToolCallsSequential(
context::agentContext,
assistantMsg::assistantMessage,
toolCalls::vector{agentToolCall},
config::agentLoopConfig,
signal::union{nothing,abortSignal},
emit::Function,
)::agentToolCallBatch
finalizedCalls = finalizedOutcome[]
messages = toolResultMessage[]
for tc in toolCalls
emit(toolExecStartEvent(tc.id, tc.name, tc.arguments))
prep = prepareToolCall(context, assistantMsg, tc, config, signal)
if prep isa immediateOutcome
finalized = finalizedOutcome(tc, prep.result, prep.isError)
else
executed = executePreparedToolCall(prep, signal, emit)
finalized = finalizeExecutedToolCall(context, assistantMsg, prep, executed, config, signal)
end
emitToolExecutionEnd(finalized, emit)
push!(messages, createToolResultMessage(finalized))
push!(finalizedCalls, finalized)
if signal !== nothing && signal.aborted
break
end
end
return agentToolCallBatch(messages, shouldTerminate(finalizedCalls))
end
# ── parallel execution ──────────────────────────────────────────
"""
executeToolCallsParallel(context, assistantMsg, toolCalls, config, signal, emit) ->
agentToolCallBatch
Prepares all tool calls concurrently and spawns a task for each
prepared call. Immediate outcomes are resolved instantly. Task
entries are collected in order, then `fetch`ed to await all
concurrent executions. Tool result messages are created from
finalized outcomes in order and returned as a batch. Respects
the abort signal — if aborted during preparation, remaining
calls are skipped. Finalization order preserves the original
call order.
Parallel execution is appropriate when the assistant requests
independent tools — for example, reading multiple files, querying
separate databases, or making independent API calls. It reduces
wall-clock time compared to sequential execution. The tradeoff is
that parallel calls can overwhelm external resources (rate limits,
connection pools, disk I/O). Finalization preserves the original
call order so tool result messages appear in the same order the
assistant requested them, regardless of which call finishes first.
# Arguments
- `context::agentContext`: Current agent context
- `assistantMsg::assistantMessage`: The assistant message containing tool calls
- `toolCalls::Vector{agentToolCall}`: Tool calls to execute (order preserved in output)
- `config::agentLoopConfig`: Loop configuration
- `signal::Union{Nothing,AbortSignal}`: Optional abort signal
- `emit::Function`: Event emitter
# Returns
- `agentToolCallBatch`: Result messages (in original call order) and termination flag
# Notes
- All tool calls are prepared before any execution begins
- Execution tasks run concurrently; `fetch` waits for completion in order
- Immediate outcomes (errors/blocks) resolve instantly without spawning tasks
- Aborting during preparation skips remaining preparations but does not
cancel tasks already running
# Examples
```julia
# Three independent reads — all succeed, results ordered by original call order
executeToolCallsParallel(ctx, msg, [readA, readB, readC], config, nothing, emit)
# => agentToolCallBatch([resultA, resultB, resultC], false)
# Mix of immediate error and concurrent success
executeToolCallsParallel(ctx, msg, [badTc, goodTc], config, nothing, emit)
# => agentToolCallBatch([errorResult, goodResult], false)
# Abort during preparation
executeToolCallsParallel(ctx, msg, [tc1, tc2, tc3], config, abortedSignal, emit)
# => agentToolCallBatch([...], false) # only prepared calls complete
```
"""
function executeToolCallsParallel(
context::agentContext,
assistantMsg::assistantMessage,
toolCalls::vector{agentToolCall},
config::agentLoopConfig,
signal::union{nothing,abortSignal},
emit::Function,
)::agentToolCallBatch
entries = union{finalizedOutcome,task{finalizedOutcome}}[]
for tc in toolCalls
emit(toolExecStartEvent(tc.id, tc.name, tc.arguments))
prep = prepareToolCall(context, assistantMsg, tc, config, signal)
if prep isa immediateOutcome
finalized = finalizedOutcome(tc, prep.result, prep.isError)
emitToolExecutionEnd(finalized, emit)
push!(entries, finalized)
else
task = task() do
executed = executePreparedToolCall(prep, signal, emit)
finalized = finalizeExecutedToolCall(context, assistantMsg, prep, executed, config, signal)
emitToolExecutionEnd(finalized, emit)
return finalized
end
schedule(task)
push!(entries, task)
end
if signal !== nothing && signal.aborted
break
end
end
finalizedCalls = finalizedOutcome[]
for entry in entries
outcome = entry isa task ? fetch(entry) : entry
push!(finalizedCalls, outcome)
end
messages = toolResultMessage[]
for f in finalizedCalls
push!(messages, createToolResultMessage(f))
end
return agentToolCallBatch(messages, shouldTerminate(finalizedCalls))
end
"""
executeToolCalls(context, assistantMsg, toolCalls, config, signal, emit) ->
agentToolCallBatch
Dispatches to sequential or parallel execution. Uses sequential mode
when `config.toolExecution == "sequential"` or when any of the
tool calls reference a tool with `executionMode: "sequential"`.
Otherwise uses parallel execution. This is the entry point called
from `streamAssistantResponse` in the agent loop.
The sequential mode takes priority over parallel because it is the
safe default. If even one tool in a batch is marked sequential, all
tools execute sequentially — this prevents a single dependent tool
from racing with an otherwise independent one. The per-tool
`executionMode` allows fine-grained control (e.g. most tools are
parallel but a specific write tool is sequential), while the config-level
`toolExecution` provides a global override.
# Arguments
- `context::agentContext`: Current agent context (used for per-tool `executionMode` lookup)
- `assistantMsg::assistantMessage`: The assistant message containing tool calls
- `toolCalls::Vector{agentToolCall}`: Tool calls to execute
- `config::agentLoopConfig`: Loop configuration (`toolExecution` mode)
- `signal::Union{Nothing,AbortSignal}`: Optional abort signal
- `emit::Function`: Event emitter
# Returns
- `agentToolCallBatch`: The result batch from the selected execution strategy
# Notes
- Per-tool `executionMode` is checked against `context.tools` for each tool call
- If any tool is sequential, the entire batch runs sequentially
- `config.toolExecution` can override all per-tool settings globally
# Examples
```julia
# Parallel dispatch — no sequential tools in batch
executeToolCalls(ctx, msg, [searchTc, fetchTc], configParallel, nothing, emit)
# => agentToolCallBatch(results, false) # parallel execution
# Sequential fallback — one tool is marked sequential
executeToolCalls(ctx, msg, [searchTc, writeTc], configParallel, nothing, emit)
# => agentToolCallBatch(results, false) # sequential because writeTc is sequential
# Global override — config forces sequential regardless of per-tool settings
executeToolCalls(ctx, msg, [searchTc, fetchTc], configSequential, nothing, emit)
# => agentToolCallBatch(results, false) # sequential because config says so
```
"""
function executeToolCalls(
context::agentContext,
assistantMsg::assistantMessage,
toolCalls::vector{agentToolCall},
config::agentLoopConfig,
signal::union{nothing,abortSignal},
emit::Function,
)::agentToolCallBatch
hasSequential = false
for tc in toolCalls
for t in context.tools
if t.name == tc.name && get(t.executionMode, "parallel") == "sequential"
hasSequential = true
break
end
end
if hasSequential
break
end
end
if config.toolExecution == "sequential" || hasSequential
return executeToolCallsSequential(context, assistantMsg, toolCalls, config, signal, emit)
else
return executeToolCallsParallel(context, assistantMsg, toolCalls, config, signal, emit)
end
end
src/type.jl
+188
View File
@@ -396,6 +396,7 @@ mutable struct yiemAgent <: agent # High-level agent wrapper
sessionId::Union{String, Nothing} # Optional session identifier
maxRetryDelayMs::Union{Int64, Nothing} # Maximum delay between retries (ms)
parallelToolExecute::Bool # Default: false
agentEventSink::Function # agent emits its status via this function
end
"""
@@ -419,6 +420,7 @@ on `inputChannel` and `followUpChannel` channels concurrently.
- `sessionId::Union{String, Nothing}`: Optional session identifier (default: `nothing`)
- `maxRetryDelayMs::Union{Int64, Nothing}`: Maximum delay between retries in milliseconds (default: `nothing`)
- `parallelToolExecute::Bool`: Run tool calls in parallel (default: `false`)
- `agentEventSink::Function`: Callback to receive agent events
# Returns
- A new `yiemAgent` instance with an active background task
@@ -444,6 +446,7 @@ function yiemAgent(
sessionId::Union{String, Nothing}=nothing,
maxRetryDelayMs::Union{Int64, Nothing}=nothing,
parallelToolExecute::Bool=false,
agentEventSink::Function,
)
# Create channels: input (user -> agent), followUp (async queue), output (agent -> user)
inputChannel = Channel(16)
@@ -467,6 +470,7 @@ function yiemAgent(
sessionId,
maxRetryDelayMs,
parallelToolExecute,
agentEventSink,
)
# Spawn the background loop and attach it
@@ -477,6 +481,190 @@ end
"""
preparedToolCall(tool, toolCall, args)
Intermediate state between tool call validation and execution.
Created after `prepareToolCall` succeeds; serves as the bridge to
the execution phase. Keeping the resolved tool, original call
metadata, and validated args together avoids repeated lookups and
allows the execution phase to access all necessary data without
carrying the full context through the call chain.
# Fields
- `tool::agentTool`: The resolved tool definition from the context
- `toolCall::agentToolCall`: The original tool call from the assistant
- `args::any`: Validated (and coerced) argument values
# Examples
```julia
# After prepareToolCall succeeds, the agent holds a preparedToolCall
prep = preparedToolCall(
tool, # agentTool found in context.tools
toolCall, # {id: "call_1", name: "search_wine", arguments: "{\"query\": \"red wine\"}"}
validatedArgs # Dict("query" => "red wine")
)
```
"""
struct preparedToolCall
tool::agentTool # The resolved tool definition from the context
toolCall::agentToolCall # The original tool call from the assistant
args::any # Validated (and coerced) argument values
end
"""
immediateOutcome(result, isError)
A tool call that was resolved without actual execution — either
because the tool was not found, validation failed, or a
`beforeToolCall` hook blocked the call. The result is produced
immediately and emitted as a tool result message.
Returning an outcome instead of throwing an exception is intentional:
it lets the agent feed the error back to the LLM as a tool result so
the model can recover — for example, by re-issuing a tool call with
corrected arguments after a validation failure.
# Fields
- `result::agentToolResult`: The pre-computed tool result
- `isError::bool`: Whether this outcome represents an error
# Examples
```julia
# Tool not found — immediate error
immediateOutcome(
createErrorToolResult("Tool search_wine not found"),
true
)
# beforeToolCall hook blocked execution
immediateOutcome(
createErrorToolResult("Tool execution was blocked"),
true
)
```
"""
struct immediateOutcome
result::agentToolResult # The pre-computed tool result
isError::bool # Whether this outcome represents an error
end
"""
executedOutcome(result, isError)
A tool call that has been executed by `tool.execute()` but has not
yet been through the `afterToolCall` hook. This intermediate state
is necessary because the hook may mutate the result (content, usage,
termination, error status). Keeping execution and finalization
separate allows the hook to inspect the raw result and decide
whether to transform it or replace it entirely.
# Fields
- `result::agentToolResult`: The tool's execution result
- `isError::bool`: Whether execution raised an error
# Examples
```julia
# Successful execution
executedOutcome(
agentToolResult([textContent("text", "Found 3 wines")], dict{any,any}(), dict{any,any}()),
false
)
# Execution error
executedOutcome(
createErrorToolResult("Connection timeout"),
true
)
```
"""
struct executedOutcome
result::agentToolResult # The tool's execution result
isError::bool # Whether execution raised an error
end
"""
finalizedOutcome(toolCall, result, isError)
The complete outcome of a tool call after both execution and the
`afterToolCall` hook. This is the final form used to construct
the `toolResultMessage` emitted to the agent loop.
The three-phase design (prepare → execute → finalize) exists so
that each phase has a single responsibility: preparation handles
validation and gating, execution performs the actual work, and
finalization applies post-processing hooks. This separation allows
the agent loop to emit `toolExecutionEnd` events with the
finalized data while keeping each phase independently testable
and swappable.
# Fields
- `toolCall::agentToolCall`: The original tool call reference
- `result::agentToolResult`: The final tool result (post-afterToolCall)
- `isError::bool`: Whether the call failed or was blocked
# Examples
```julia
# Normal successful finalization
finalizedOutcome(tc, agentToolResult(content, details, usage, false), false)
# afterToolCall mutated result and set terminate
finalizedOutcome(tc, agentToolResult(content, details, usage, true), false)
```
"""
struct finalizedOutcome
toolCall::agentToolCall # The original tool call reference
result::agentToolResult # The final tool result (post-afterToolCall)
isError::bool # Whether the call failed or was blocked
end
"""
agentToolCallBatch(messages, terminate)
A batch of tool result messages from executing one or more tool calls.
The `terminate` flag indicates whether all tools in the batch
requested termination, which causes the agent loop to stop
processing further turns.
This flag is set by the tool implementation (not the end user) to
signal that the agent should not call the LLM again. Typical use
cases:
- Task completion: a tool like `deploy` or `submit` finishes its
work and returns `terminate: true` so the agent stops instead
of asking the LLM what to do next.
- Unrecoverable error: a tool hits a fatal condition (e.g.
database connection lost, auth token expired) and returns
`terminate: true` so the agent stops with an error message
rather than retrying.
- Async handoff: a tool triggers a long-running external
operation and wants the agent to stop now; the external system
will later resume the agent via `continue()`.
If `terminate` is `false` (default), the agent loop feeds the tool
results back to the LLM for another turn.
# Fields
- `messages::Vector{toolResultMessage}`: Tool result messages for this batch
- `terminate::Bool`: Whether the batch should terminate the loop
# Examples
```julia
# Batch of 3 tool results, no termination
agentToolCallBatch(resultMessages, false)
# All tools requested termination
agentToolCallBatch(resultMessages, true)
# Empty batch — terminate is false regardless
agentToolCallBatch(toolResultMessage[], false)
```
"""
struct agentToolCallBatch
messages::vector{toolResultMessage} # Tool result messages for this batch
terminate::bool # Whether the batch should terminate the loop
end