279 lines
11 KiB
Julia
279 lines
11 KiB
Julia
"""
|
|
Tool that writes new Julia tool module files to disk.
|
|
|
|
The agent can use this tool when it encounters a task that no existing tool
|
|
can handle. Provide the tool's name, label, description, inputSchema, and
|
|
execute logic as Julia code. The tool is written to `src/tools/<name>.jl`.
|
|
|
|
After calling this tool, restart the agent so `loadTools("src/tools")` picks
|
|
up the new file. The new tool is immediately available.
|
|
|
|
# Example
|
|
|
|
1. Agent calls writeTool with a spec for a "searchWine" tool
|
|
2. writeTool generates src/tools/searchWine.jl
|
|
3. Restart agent — loadTools() picks up the new file
|
|
4. Agent calls searchWine with args
|
|
|
|
# How It Works
|
|
|
|
writeTool is a **file writer**, not a code generator. The LLM provides the
|
|
tool logic as `executeCode`, and writeTool wraps it in Julia boilerplate:
|
|
- Converts `inputSchema` Dict into Julia `Dict{String,Any}(...)` string
|
|
- Indents `executeCode` with 4 spaces
|
|
- Wraps it inside `function executeTool(...)::agentToolResult ... end`
|
|
- Appends `getTool()` returning an `agentTool` struct
|
|
- Writes the combined string to `src/tools/<name>.jl`
|
|
|
|
# Important Notes
|
|
|
|
- The `executeCode` string is embedded literally into the generated tool.
|
|
Use `args["param_name"]` to access input parameters.
|
|
- The code string should be the function body (NOT wrapped in a function).
|
|
Lines will be indented with 4 spaces inside the execute function.
|
|
- Tool names must be valid Julia identifiers (lowercase letters, digits, underscores,
|
|
no leading digits or special characters).
|
|
"""
|
|
|
|
"""
|
|
Validate that a tool name is a valid Julia identifier.
|
|
"""
|
|
function validateToolName(name::String)::Union{Nothing,String}
|
|
if !occursin(r"^[a-zA-Z_][a-zA-Z0-9_!]*$", name)
|
|
return "Invalid tool name: '$name'. Tool names must be valid Julia identifiers (letters, digits, underscores, starting with a letter or underscore)."
|
|
end
|
|
return nothing
|
|
end
|
|
|
|
"""
|
|
Execute the writeTool.
|
|
|
|
Generates a new .jl tool file and registers it with the tool registry.
|
|
"""
|
|
function executeTool(toolCallId::String, args::Dict{String,Any}, signal::Union{Nothing,abortSignal}, onPartialResult::Function)::agentToolResult
|
|
tool_name = get(args, "name", "")::String
|
|
tool_label = get(args, "label", tool_name)::String
|
|
tool_description = get(args, "description", "")::String
|
|
tool_schema = get(args, "inputSchema", Dict{String,Any}())::Dict{String,Any}
|
|
execute_code = get(args, "executeCode", "")::String
|
|
validate_code = get(args, "validateCode", nothing)::Union{String,Nothing}
|
|
prepare_code = get(args, "prepareCode", nothing)::Union{String,Nothing}
|
|
parallel = get(args, "parallel", false)::Bool
|
|
|
|
# Validate tool name
|
|
name_err = validateToolName(tool_name)
|
|
if name_err !== nothing
|
|
return agentToolResult(
|
|
[textContent(name_err)],
|
|
Dict{Any,Any}(), nothing, false
|
|
)
|
|
end
|
|
|
|
# Validate required fields
|
|
if isempty(tool_name)
|
|
return agentToolResult(
|
|
[textContent("Missing required field: 'name'")],
|
|
Dict{Any,Any}(), nothing, false
|
|
)
|
|
end
|
|
if isempty(tool_description)
|
|
return agentToolResult(
|
|
[textContent("Missing required field: 'description'")],
|
|
Dict{Any,Any}(), nothing, false
|
|
)
|
|
end
|
|
if isempty(execute_code)
|
|
return agentToolResult(
|
|
[textContent("Missing required field: 'executeCode'")],
|
|
Dict{Any,Any}(), nothing, false
|
|
)
|
|
end
|
|
|
|
onPartialResult(Dict("status" => "Generating tool: $tool_name"))
|
|
|
|
# Build the tool file path
|
|
script_dir = dirname(@__FILE__)
|
|
tools_dir = dirname(script_dir)
|
|
filepath = joinpath(tools_dir, "$(tool_name).jl")
|
|
|
|
# Check for naming conflicts
|
|
if isfile(filepath)
|
|
return agentToolResult(
|
|
[textContent("Tool file already exists: $filepath. Rename the tool or delete the existing file first.")],
|
|
Dict{Any,Any}(), nothing, false
|
|
)
|
|
end
|
|
|
|
onPartialResult(Dict("status" => "Writing file: $(basename(filepath))"))
|
|
|
|
# Convert schema Dict to a Julia Dict literal string
|
|
schema_literal = dict_to_julia_literal(tool_schema)
|
|
|
|
# Build optional validation function
|
|
validate_section = if validate_code !== nothing && !isempty(validate_code)
|
|
indented = indent_code(validate_code, 4)
|
|
"function validateRequiredArgs(args::Dict{String,Any})::Union{Nothing,String}\n$indented\n return nothing\nend\n"
|
|
else
|
|
""
|
|
end
|
|
|
|
# Build optional prepare function
|
|
prepare_section = if prepare_code !== nothing && !isempty(prepare_code)
|
|
indented = indent_code(prepare_code, 4)
|
|
"function prepareArguments(args::Dict{String,Any})::Dict{String,Any}\n$indented\n return args\nend\n"
|
|
else
|
|
""
|
|
end
|
|
|
|
# Indent user's execute code for embedding inside execute function body
|
|
indented_exec = indent_code(execute_code, 4)
|
|
|
|
# Escape description for Julia string literal
|
|
escaped_desc = replace(tool_description, "\\" => "\\\\")
|
|
escaped_desc = replace(escaped_desc, "\"" => "\\\"")
|
|
|
|
# Build the complete tool file content
|
|
parts = String[]
|
|
push!(parts, "# Auto-generated tool: $tool_name\n")
|
|
push!(parts, "# Generated by writeTool at $(now())\n\n")
|
|
if !isempty(validate_section)
|
|
push!(parts, validate_section)
|
|
push!(parts, "\n")
|
|
end
|
|
if !isempty(prepare_section)
|
|
push!(parts, prepare_section)
|
|
push!(parts, "\n")
|
|
end
|
|
push!(parts, "\n")
|
|
push!(parts, "# Execute function\n")
|
|
push!(parts, "function executeTool(toolCallId::String, args::Dict{String,Any}, signal::Union{Nothing,abortSignal}, onPartialResult::Function)::agentToolResult\n")
|
|
push!(parts, "$indented_exec\n")
|
|
push!(parts, "end\n\n")
|
|
push!(parts, "# Tool definition\n")
|
|
push!(parts, "function getTool()::agentTool\n")
|
|
push!(parts, " return agentTool(\n")
|
|
push!(parts, " name = \"$(tool_name)\",\n")
|
|
push!(parts, " label = \"$(tool_label)\",\n")
|
|
push!(parts, " description = \"$(escaped_desc)\",\n")
|
|
push!(parts, " inputSchema = $schema_literal,\n")
|
|
push!(parts, " execute = executeTool,\n")
|
|
if validate_code !== nothing && !isempty(validate_code)
|
|
push!(parts, " validateRequiredArgs = validateRequiredArgs,\n")
|
|
else
|
|
push!(parts, " validateRequiredArgs = nothing,\n")
|
|
end
|
|
if prepare_code !== nothing && !isempty(prepare_code)
|
|
push!(parts, " prepareArguments = prepareArguments,\n")
|
|
else
|
|
push!(parts, " prepareArguments = nothing,\n")
|
|
end
|
|
push!(parts, " parallelToolExecute = $parallel\n")
|
|
push!(parts, " )\n")
|
|
push!(parts, "end\n")
|
|
|
|
tool_code = join(parts)
|
|
|
|
# Write the file — tool is loaded on next agent restart via loadTools()
|
|
write(filepath, tool_code)
|
|
|
|
onPartialResult(Dict("status" => "Done"))
|
|
|
|
return agentToolResult(
|
|
[textContent("Tool '$(tool_name)' written to $filepath. Restart the agent so loadTools() picks it up, then call listTools to verify.")],
|
|
Dict{Any,Any}(
|
|
"file" => filepath,
|
|
"name" => tool_name,
|
|
"label" => tool_label,
|
|
"description" => tool_description,
|
|
),
|
|
nothing, false
|
|
)
|
|
end
|
|
|
|
"""
|
|
Indent a multi-line code string by the specified number of spaces.
|
|
"""
|
|
function indent_code(code::String, n::Int)::String
|
|
prefix = " "^n
|
|
lines = split(code, '\n')
|
|
result_lines = String[prefix * line for line in lines]
|
|
return join(result_lines, "\n")
|
|
end
|
|
|
|
"""
|
|
Convert a Julia Dict to a valid Julia Dict{String,Any}(...) literal string.
|
|
"""
|
|
function dict_to_julia_literal(d)::String
|
|
if d isa Dict
|
|
items = String[]
|
|
for (k, v) in d
|
|
key_str = json_string(k)
|
|
val_str = value_to_julia(v)
|
|
push!(items, "$key_str => $val_str")
|
|
end
|
|
return "Dict{String,Any}(" * join(items, ", ") * ")"
|
|
else
|
|
return value_to_julia(d)
|
|
end
|
|
end
|
|
|
|
function value_to_julia(v)::String
|
|
if v isa Dict
|
|
return dict_to_julia_literal(v)
|
|
elseif v isa Vector
|
|
items = [value_to_julia(x) for x in v]
|
|
return "[" * join(items, ", ") * "]"
|
|
elseif v isa String
|
|
escaped = replace(v, "\\" => "\\\\")
|
|
escaped = replace(escaped, "\"" => "\\\"")
|
|
return "\"$escaped\""
|
|
elseif v isa Number
|
|
return string(v)
|
|
elseif v isa Bool
|
|
return string(v)
|
|
elseif v === nothing
|
|
return "nothing"
|
|
else
|
|
return "\"$(v)\""
|
|
end
|
|
end
|
|
|
|
"""
|
|
Convert any Julia value to a JSON string.
|
|
"""
|
|
function json_string(v)::String
|
|
return JSON.json(v)
|
|
end
|
|
|
|
"""
|
|
Define and return the writeTool agentTool.
|
|
"""
|
|
function getTool()::agentTool
|
|
return agentTool(
|
|
name = "writeTool",
|
|
label = "Create Tool",
|
|
description = "Write a new Julia tool module file to src/tools/<name>.jl. The LLM provides the tool logic as executeCode; writeTool wraps it in Julia boilerplate and writes the file. Restart the agent to load the new tool.",
|
|
inputSchema = Dict{String,Any}(
|
|
"type" => "object",
|
|
"properties" => Dict(
|
|
"name" => Dict("type" => "string", "description" => "Unique tool name (valid Julia identifier, no spaces or special chars)"),
|
|
"label" => Dict("type" => "string", "description" => "Human-readable tool name shown in tool descriptions"),
|
|
"description" => Dict("type" => "string", "description" => "What the tool does (shown to LLM for tool selection decisions)"),
|
|
"inputSchema" => Dict(
|
|
"type" => "object",
|
|
"description" => "JSON Schema describing tool parameters in MCP format"
|
|
),
|
|
"executeCode" => Dict("type" => "string", "description" => "Julia code for the execute function body. Use args[\"key\"] to access parameters. Do NOT wrap in a function definition."),
|
|
"validateCode" => Dict("type" => "string", "optional" => true, "description" => "Optional custom validation Julia code (runs before execute). Use args[\"key\"] to access parameters. Return nothing to pass, or a string error message to fail."),
|
|
"prepareCode" => Dict("type" => "string", "optional" => true, "description" => "Optional argument preparation code (runs before validation). Return modified args dict."),
|
|
"parallel" => Dict("type" => "boolean", "default" => false, "description" => "Whether this tool can run in parallel with other tools")
|
|
),
|
|
"required" => ["name", "label", "description", "inputSchema", "executeCode"]
|
|
),
|
|
execute = executeTool,
|
|
prepareArguments = nothing,
|
|
validateRequiredArgs = nothing,
|
|
parallelToolExecute = false
|
|
)
|
|
end
|