hastekit.NewTool for a function with typed arguments and a typed result. The helper derives a JSON schema from the input type, decodes arguments, invokes the function, and encodes its result.
Define a typed tool
This package defines a tool ready to add toAgentConfig.Tools:
Tools: []hastekit.Tool{tools.Add}. Give production tools explicit, stable names and descriptions. Validate semantic constraints inside the function; a model-visible schema is not an authorization check.
A tool should pass ctx to database, HTTP, and other blocking calls. Tools can run concurrently, so shared clients and mutable state must be safe for concurrent use. Retried durable steps can repeat external side effects; use an idempotency key at the external system when needed.
Implement the interface directly
For stateful tools, progress reporting, or interruption/continuation, implementagents.Tool:
pkg/agents. Embed *agents.BaseTool to supply GetToolDescriptor, and implement Execute. BaseTool.ToolUnion contains the model-visible function schema; RequiresApproval and Deferred control execution and discovery.
ToolCall includes arguments, call IDs, namespace, thread and session IDs, application run context, and saved tool state. Return state changes through ToolCallResponse.StateUpdates; do not mutate ToolCall.State. Durable workers receive a serialized copy of the input.
For a text result, use agents.ToolCallResult(call, text). It copies the matching call IDs into the result.
Tool annotations
Annotations are behavioral hints. Approval is a separate execution control. Read hints from
tool.GetToolDescriptor().Annotations; the Is* methods are nil-safe. Unset destructive/open-world hints use conservative true defaults, while read-only/idempotent default to false.
See middleware for using the descriptor in a permission policy and human input for approval.
Report progress
A custom tool can callcall.ReportProgress(ctx, agents.ToolProgress{Progress: 3, Total: 10, Message: "Fetched three records"}). Reporting is best-effort and safe when no reporter is installed. MCP progress notifications use the same stream. Progress is a live event, not a durable business checkpoint.