ZKIT / OPEN-SOURCE GO AGENT TOOLKIT
Go packages for building AI agents.
zkit contains the runner, tools, and model clients used by zarlcode.
Import them into a CLI, a service, or another Go application. You choose which model to call, which tools it can use, and how to check its work. You don’t need to install zarlcode to use zkit.
go get github.com/zarldev/zarlmono/zkit@latest01 / RUNNING A TASK
How the runner works
Your application calls Runner.Run with a task. The runner sends requests to the model, runs the tools it asks for, and returns their results for the next request.
- 01 / PREPARE
Prepare the conversation
Load the prompt, available tools, and any messages the user sent while the task was running. An opted-in input source also admits completed child results as host observations at safe history boundaries. If compaction is configured, shorten the history when it approaches the model’s context limit.
- 02 / REQUEST
Call the model
A provider adapter sends the conversation and tool definitions to a hosted or local model. As the response arrives, the runner can notify your application of new text and tool calls.
- 03 / TOOLS
Run the requested tools
The tool source looks up and executes each call. If you have added guardrails, they can fix malformed arguments, reject a call, or add advice to its result.
- 04 / REPEAT
Send the results back
Add the tool results to the conversation and call the model again. With automatic child input enabled, a parent with outstanding work waits for completion input rather than polling or finishing early. Otherwise, a no-tool response can finish once completion checks accept; limits, cancellation, and unrecoverable errors can also stop the run.
Recording what happened
Use an event sink to display progress or write logs. If you also need to save and resume conversations, your application must arrange that storage. zarlcode saves its transcripts and model history separately in SQLite.
Runner events ↗Checking the result
TaskResult contains the response, any error, and the reason the loop ended. TerminalCompleted means the runner accepted completion, including configured gates and input admission—it is not independent proof that the code is correct. The pursue package can run a check you provide, such as a test command, and retry with the failure output. You set the maximum number of attempts.
Tools run with the access your application gives them. Shell checks can reject known dangerous commands, but they do not isolate a process from your machine. Configure sandboxing separately where supported, and set timeouts and iteration limits to stop runaway tasks. Sandboxing guide ↗
02 / SETUP
Create a runner
Pass a model client and a tool registry to runner.New, then call Run with your task. The registry tells the model which tools are available and how to call them.
Runner options let you set timeouts, limit iterations, handle progress events, or shorten long conversations. Guardrails wrap the tool source to check calls before or after execution. These are optional; you configure the ones you need.
The code shown here is from the quickstart. The complete program includes imports, Anthropic setup, and a weather tool.
Read the complete program ↗r := runner.New(runner.ClientFromProvider(prov),
runner.WithTools(tools.NewRegistry(newWeatherTool())),
runner.WithMaxIterations(8),
)
res := r.Run(context.Background(), runner.TaskSpec{Prompt: "What is the weather in Oslo?"})
if res.Err != nil {
log.Fatal(res.Err)
}
if res.Reason != runner.TerminalCompleted {
log.Fatalf("agent stopped: %s", res.Reason)
}
fmt.Println(res.FinalContent)03 / CUSTOMIZATION
Add your own implementations
Implement these Go interfaces to add a model client, supply tools, handle events, or change how the runner manages history and checks results.
runner.ClientCalling a model- Connect a model API to the runner’s completion method. You can also return scripted responses to test tool handling without making network requests. Provider reference ↗
runner.ToolSourceProviding tools- List the tools available to the model and execute its calls. A registry implements this interface, as does a guardrail wrapper around that registry. MCP connections can provide tools from external servers; review what those tools can access before enabling them. Tool system ↗
runner.EventSinkHandling progress- Receive events as text arrives, tools run, and tasks start or finish. Use them to update a UI or write logs. The runner does not depend on how you display the results. Runner reference ↗
compact.CompactorShortening history- Control which model messages are summarized or removed when the conversation gets too long. Save a separate transcript if users need to review or export the full session later. Compaction strategies ↗
pursue.GoalChecking success- Check whether tests pass, a file exists, or another required condition holds. If the check fails, return feedback for the next attempt. Verification reference ↗
04 / PACKAGE REFERENCE
Runtime packages
Each reference page covers setup, options, and behavior in more detail.
runner
Calls the model, runs the tools it requests, and reports why the task stopped.
tools
Defines the tools a model can call, their arguments, and the results returned to it.
providers
Connects hosted and local model APIs to the runner.
guardrails
Checks tool arguments and shell commands, and sends errors or advice back to the model.
compact
Summarizes or trims model history to keep requests within the context limit.
pursue
Checks whether a task succeeded and retries with feedback, up to a limit you set.
Delegating work to other agents
The spawn tools start tasks using named agent profiles and immediately return a receipt. With automatic input enabled, completed child results arrive directly as input to their parent model; no await call is needed just to receive them. Explicit status, wait, and cancellation tools remain available. When agents share a workspace, the application also needs to coordinate their file changes.
Sub-agent tasks ↗Retrieval and longer workflows
Other packages can retrieve relevant documents, run a graph of steps, save checkpoints, or ask a person to approve an action. Use these when your task needs more than a conversation with tools.
Retrieval, workflows, and storage ↗05 / IN THIS REPOSITORY
Applications using zkit
Read how the CLI and evaluation driver configure the runner, or try a small example to test a particular feature.
zarlcode
The coding agent adds a terminal UI, workspace settings, provider setup, and saved sessions to the zkit runner.
EVALUATIONswebench-eval
The SWE-bench driver uses the same coding tools and guardrails as zarlcode. Its guide covers task execution, result checking, and retry logs.
EXAMPLESRunnable examples
Small programs demonstrating individual features. Several have scripted modes that run without an API key or a live model.