Skip to main content
Use 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 to AgentConfig.Tools:
Register it as 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, implement agents.Tool:
These names belong to 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 call call.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.