Documentation
¶
Overview ¶
Package claudetool converts unified toolcall.Tool definitions into Claude-compatible anthropic.ToolParam metadata for use with the [claudeexecutor].
This package mirrors [googletool] and [openaistool], providing tool conversion and error formatting for tool handlers that receive anthropic.ToolUseBlock values.
Tool Conversion ¶
Use FromTool to convert a single unified tool, or Map to batch-convert an entire tool map:
tools := claudetool.Map[MyResponse](unifiedTools)
Each converted tool automatically injects a "reasoning" parameter that the model must fill in to explain its intent before making the call.
Error Formatting ¶
Use Error to build tool error responses:
return claudetool.Error("file not found: %s", path)
Thread Safety ¶
All functions in this package are safe for concurrent use.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Error ¶
Error creates an error response map for Claude tool calls
Example ¶
ExampleError demonstrates creating simple error responses.
package main
import (
"fmt"
"chainguard.dev/driftlessaf/agents/toolcall/claudetool"
)
func main() {
// Simple error
errResp := claudetool.Error("File not found")
fmt.Printf("Simple error: %v\n", errResp)
// Formatted error
filename := "data.txt"
errResp = claudetool.Error("Cannot read file %s: permission denied", filename)
fmt.Printf("Formatted error: %v\n", errResp["error"])
}
Output: Simple error: map[error:File not found] Formatted error: Cannot read file data.txt: permission denied
func Map ¶
Map converts a unified tool map to Claude-specific metadata.
Example ¶
ExampleMap demonstrates converting a map of unified tools to Claude-specific metadata.
package main
import (
"context"
"fmt"
"chainguard.dev/driftlessaf/agents/agenttrace"
"chainguard.dev/driftlessaf/agents/toolcall"
"chainguard.dev/driftlessaf/agents/toolcall/claudetool"
)
func main() {
// Define a map of unified tools.
tools := map[string]toolcall.Tool[string]{
"greet": {
Def: toolcall.Definition{
Name: "greet",
Description: "Greet a person by name.",
},
Handler: func(_ context.Context, _ toolcall.ToolCall, _ *agenttrace.Trace[string], _ *string) map[string]any {
return map[string]any{"greeting": "Hello!"}
},
},
"farewell": {
Def: toolcall.Definition{
Name: "farewell",
Description: "Say farewell to a person.",
},
Handler: func(_ context.Context, _ toolcall.ToolCall, _ *agenttrace.Trace[string], _ *string) map[string]any {
return map[string]any{"farewell": "Goodbye!"}
},
},
}
// Convert all tools to Claude-specific metadata.
meta := claudetool.Map(tools)
fmt.Println(len(meta))
}
Output: 2
Types ¶
type Metadata ¶
type Metadata[Response any] struct { // Definition is the tool definition for Claude. Definition anthropic.ToolParam // Handler processes the tool call. // If the handler sets *result to a non-zero value, the executor will immediately exit with that response. Handler func( ctx context.Context, toolUse anthropic.ToolUseBlock, trace *agenttrace.Trace[Response], result *Response, ) map[string]any }
Metadata describes a tool available to the Claude agent.
func FromTool ¶
FromTool converts a unified tool to Claude-specific metadata.
Example ¶
ExampleFromTool demonstrates converting a unified tool to Claude-specific metadata.
package main
import (
"context"
"fmt"
"chainguard.dev/driftlessaf/agents/agenttrace"
"chainguard.dev/driftlessaf/agents/toolcall"
"chainguard.dev/driftlessaf/agents/toolcall/claudetool"
)
func main() {
// Define a unified tool that works with any provider.
tool := toolcall.Tool[string]{
Def: toolcall.Definition{
Name: "greet",
Description: "Greet a person by name.",
Parameters: []toolcall.Parameter{{
Name: "name",
Type: "string",
Description: "The name of the person to greet.",
Required: true,
}},
},
Handler: func(_ context.Context, call toolcall.ToolCall, _ *agenttrace.Trace[string], _ *string) map[string]any {
name, _ := call.Args["name"].(string)
return map[string]any{"greeting": "Hello, " + name + "!"}
},
}
// Convert the unified tool to Claude-specific metadata.
meta := claudetool.FromTool(tool)
fmt.Println(meta.Definition.Name)
}
Output: greet
type SubmitMetadata ¶ added in v0.7.59
type SubmitMetadata[Response any] struct { // Definition is the tool definition for Claude. Definition anthropic.ToolParam // Handler parses a submit tool call into a SubmitOutcome. It performs no // side effects on the run: committing the response is the executor's // decision. The handler records the trace tool call for parameter and // parse failures (Accepted=false); the executor records accepted calls so // their completion reflects the validation verdict. Handler func( ctx context.Context, toolUse anthropic.ToolUseBlock, trace *agenttrace.Trace[Response], ) toolcall.SubmitOutcome[Response] }
SubmitMetadata describes the terminal submit tool for the Claude executor. It is registered via the executor's WithSubmitResultProvider option rather than the regular tool map because the submit tool is special: its accepted outcome — once the executor's result validators pass — becomes the run's final result and ends the agent loop.
Source Files