Gojent

A small, strongly typed agent runtime for Go.
Gojent gives you one streaming-first execution loop, typed tools,
provider-neutral messages, and a minimal persistence contract. There is no
workflow engine and no hidden state: an agent is a Go value, a run is a method
call, and composition is ordinary Go code.
- Small core. Four packages:
agent, llm, tool, and session.
Zero third-party dependencies in the root module.
- Typed tools. Tool input and output are Go types. JSON Schema is generated
and validated before your handler runs.
- Streaming first.
Generate and Stream are adapters over the same loop.
- Provider neutral. OpenAI, Anthropic, and Gemini adapters live in separate
modules behind one
llm.Model interface.
- No framework lock-in. Policies, stores, observability, and providers are
small interfaces you can implement yourself.
The repository also ships codjent, a sample coding
agent that demonstrates the runtime in a real application.
Contents
Install
Go 1.25.5 or newer is required.
go get github.com/ijaidev/gojent@latest
Optional providers and stores are separate modules:
go get github.com/ijaidev/gojent/providers/anthropic
go get github.com/ijaidev/gojent/providers/google
go get github.com/ijaidev/gojent/providers/openai
go get github.com/ijaidev/gojent/stores/sqlite
go get github.com/ijaidev/gojent/stores/postgres
Quickstart
This program needs no API key and no modules beyond the root package. It uses
the deterministic mock model that ships with Gojent:
package main
import (
"context"
"fmt"
"log"
"github.com/ijaidev/gojent/core/agent"
"github.com/ijaidev/gojent/providers/mockllm"
)
func main() {
model := mockllm.New("Gojent is a small, typed agent runtime for Go.")
assistant, err := agent.New(agent.Config{
Name: "assistant",
Instructions: "Answer in one sentence.",
Model: model,
})
if err != nil {
log.Fatal(err)
}
response, err := assistant.Generate(context.Background(), "What is Gojent?")
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Text)
}
Gojent is a small, typed agent runtime for Go.
Swap the mock for a provider, define a tool from Go types, and the runtime runs
the model/tool loop until the model answers:
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/ijaidev/gojent/core/agent"
"github.com/ijaidev/gojent/core/session"
"github.com/ijaidev/gojent/core/tool"
"github.com/ijaidev/gojent/providers/google"
)
type WeatherInput struct {
City string `json:"city" description:"City name, e.g. Tokyo"`
}
type WeatherOutput struct {
City string `json:"city"`
TemperatureC float64 `json:"temperature_c"`
}
func main() {
ctx := context.Background()
model, err := google.New(ctx, google.Config{
Model: "gemini-2.5-flash",
APIKey: os.Getenv("GEMINI_API_KEY"),
})
if err != nil {
log.Fatal(err)
}
weather := tool.MustNew(tool.Config[WeatherInput, WeatherOutput]{
ID: "get_weather",
Description: "Get the current weather for a city.",
Annotations: tool.Annotations{ReadOnly: true},
Execute: func(_ context.Context, in WeatherInput) (WeatherOutput, error) {
return WeatherOutput{City: in.City, TemperatureC: 21.5}, nil
},
})
assistant, err := agent.New(agent.Config{
Name: "assistant",
Description: "A concise weather assistant",
Instructions: "Use the weather tool when asked about current conditions.",
Model: model,
Tools: []tool.Tool{weather},
Store: session.NewMemory(),
})
if err != nil {
log.Fatal(err)
}
response, err := assistant.Generate(ctx, "What is the weather in Tokyo?",
agent.WithSession("demo", "user-1"),
)
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Text)
}
Install the provider module first:
go get github.com/ijaidev/gojent/providers/google
export GEMINI_API_KEY="..."
See Models and providers for OpenAI and Anthropic, and
examples/ for runnable versions of these programs.
Reference app: codjent
Codjent is a sample coding agent built on Gojent: a Go
backend, an embedded Next.js UI, SQLite-backed threads, streaming runs, tool
calls, and approval prompts.
It exists to show what the runtime looks like when assembled into a real
application. It is a sample, not a supported product — its scope is
deliberately small, and it has no authentication, multi-tenant isolation, or
deployment story. Treat it as a reference, not a platform.
go install github.com/ijaidev/gojent/codjent/cmd/codjent@latest
codjent
Then open http://127.0.0.1:8787. The frontend is embedded in the binary, so no
extra files are needed. Configure a provider under /settings on first run, or
start with GEMINI_API_KEY set to seed a Google provider.
Codjent is its own Go module and is versioned separately with codjent/vX.Y.Z
tags. If it is useful, copy the parts you need from
codjent/internal into your own application.
Design
Gojent is intentionally small. The core is four packages and no third-party
dependencies; adapters add weight only when you import them.
Interfaces only at the seams
The core exposes four extension points:
llm.Model (optionally llm.Streamer); Info() is required
tool.Tool
session.Store
agent.Policy, agent.Approver, and agent.Sink
The execution loop itself is private, not an interface. Generate and Stream
are the public adapters. Middleware such as tracing, caching, or redaction
belongs in wrappers around these seams.
Immutable agents, per-run configuration
An agent.Agent is reusable behavior: instructions, a model, tools, and
defaults. A run cannot mutate it. Per-run state lives in agent.RunOptions,
which is also the only public per-run configuration type.
Generate and Stream accept functional options for convenience. GenerateWith
and StreamWith accept a complete RunOptions value when you want to build one
explicitly.
Fail closed
Without a policy, tools are allowed. Once a policy is installed, it fails closed:
an unrecognized decision is treated as deny, and an Ask decision without an
approver is denied. Providers reject requests they cannot honor with
llm.ErrUnsupported instead of silently dropping options.
Atomic persistence
A store has exactly two methods, and Append is atomic. The runtime persists an
assistant tool-call message and all of its tool results in one call, so a crash
cannot leave a transcript with unanswered tool calls.
Packages
| Package |
Responsibility |
core/agent |
Immutable Agent behavior and its execution adapters. |
core/llm |
Model, canonical Message/Request/Response, streams, errors. |
core/tool |
Tool, typed Config, JSON Schema generation and validation. |
core/session |
Session identity, the two-method Store contract, Memory. |
tools |
Ready-made filesystem, command, web, and task tools. |
providers/mockllm |
Deterministic model for tests and examples (root module). |
providers/anthropic |
Anthropic Messages adapter (separate module). |
providers/google |
Google Gemini adapter (separate module). |
providers/openai |
OpenAI Responses and Chat Completions adapter (separate module). |
stores/sqlite |
Durable SQLite session store (separate module). |
stores/postgres |
Durable PostgreSQL session store (separate module). |
examples |
Runnable examples; examples/google is its own module. |
A tool is a typed function plus metadata. The constructor generates a JSON
Schema from the input type, and the runtime validates model arguments against
it before executing your handler:
type SearchInput struct {
Query string `json:"query" description:"Search query"`
Limit int `json:"limit,omitempty" description:"Maximum results, 1-20"`
}
type SearchResult struct {
Title string `json:"title"`
URL string `json:"url"`
}
search := tool.MustNew(tool.Config[SearchInput, SearchResult]{
ID: "search",
Description: "Search the knowledge base.",
Annotations: tool.Annotations{ReadOnly: true, Idempotent: true},
Execute: func(ctx context.Context, in SearchInput) (SearchResult, error) {
return SearchResult{Title: "Example", URL: "https://example.com"}, nil
},
})
Struct tags drive the schema:
json sets the property name and omitempty marks it optional;
description becomes the JSON Schema description shown to the model;
enum constrains accepted values, for example enum:"low,medium,high".
Use tool.New when you want an error, or tool.MustNew when a failure to build
a tool is a programming mistake and should panic at startup.
What the runtime guarantees
- Invalid arguments are reported back to the model as a tool error; the handler
never runs.
- Panics, timeouts, and context cancellation are contained by the runtime and
surfaced as tool errors. The default tool timeout is two minutes; set
agent.Config.ToolTimeout or agent.WithToolTimeout to change it. A negative
value disables the timeout.
- Tool results are persisted with the assistant message that requested them.
Annotations
tool.Annotations describes side effects so policies can make decisions without
knowing the implementation:
type Annotations struct {
ReadOnly bool // does not mutate state
Destructive bool // may delete or overwrite data
Idempotent bool // repeating the call has the same effect
OpenWorld bool // talks to an unbounded external system
}
Results and multimodal output
Returning a typed value makes it available as structured Data and as JSON text
for the model. To return files or media, use tool.Result:
tool.MustNew(tool.Config[struct{}, tool.Result]{
ID: "read_image",
Execute: func(ctx context.Context, _ struct{}) (tool.Result, error) {
return tool.Result{Content: []llm.Part{llm.NewTextPart("rendered")}}, nil
},
})
The root tools package bundles the common tool sets:
import (
"context"
"github.com/ijaidev/gojent/tools"
"github.com/ijaidev/gojent/tools/exec"
"github.com/ijaidev/gojent/tools/fs"
"github.com/ijaidev/gojent/tools/web"
)
fsTools, err := tools.StandardFilesystemTools(fs.Config{BaseDir: "/workspace"})
webTools, err := tools.StandardWebTools(web.FetchConfig{})
managedExec, err := tools.NewExecTools(exec.ManagerConfig{BaseDir: "/workspace"})
defer managedExec.Close(context.Background())
execTools := managedExec.All()
tracker, taskTools, err := tools.StandardTaskTools()
_ = tracker
execute_command waits in the foreground, then promotes a long-running command
to the background instead of killing it. Set background: true to start a
command immediately. Background processes are managed with process_status,
read_process_output, wait_process, and kill_process; process IDs are
opaque handles, not raw PIDs. The manager must be closed to stop any processes
that are still running. StandardExecTools remains the single foreground-only
tool for callers that do not need the managed tool set.
Filesystem tools are sandboxed to BaseDir when one is set. Command tools use
BaseDir for relative working directories, but commands run with the host
user's permissions; gate them with a policy or approver before giving them to a
model.
Streaming
Stream starts a run and returns a handle. Events are observations; they cannot
change execution. RunEnd is always the last event.
run, err := assistant.Stream(ctx, "Explain Go interfaces briefly.",
agent.WithStore(session.NewMemory()),
agent.WithSession("demo", "user-1"),
)
if err != nil {
log.Fatal(err)
}
for event := range run.Events() {
switch event := event.(type) {
case agent.TextDelta:
fmt.Print(event.Text)
case agent.RunEnd:
if event.Err != nil {
log.Print(event.Err)
}
}
}
response, err := run.Wait(ctx)
Run.Events returns a channel that closes after RunEnd. Wait does not drain
events, so a consumer that ignores Events and never cancels the run may block
the dispatcher. Either consume events or call Cancel when you abandon a run.
The runtime uses a model's Stream implementation when it also implements
llm.Streamer, and falls back to Generate otherwise. TextDelta.Replace
reports that Text is a full snapshot of the part rather than an increment.
Sessions and stores
A session.Session identifies a conversation and its owner. A store has exactly
two operations:
type Store interface {
Load(ctx context.Context, session Session) ([]llm.Message, error)
Append(ctx context.Context, session Session, messages ...llm.Message) error
}
Durability features such as checkpoints, leases, search, and conversation
metadata belong in store modules or your application, not in the core.
session.Memory is built in for tests and ephemeral applications. Use
stores/sqlite or stores/postgres when transcripts must survive a restart:
import (
"github.com/ijaidev/gojent/core/agent"
"github.com/ijaidev/gojent/stores/sqlite"
)
store, err := sqlite.New("file:gojent.db")
if err != nil {
log.Fatal(err)
}
defer store.Close()
assistant, err := agent.New(agent.Config{
Name: "assistant",
Model: model,
Store: store,
})
response, err := assistant.Generate(ctx, "Continue where we left off.",
agent.WithSession("thread-1", "user-1"),
)
stores/sqlite uses mattn/go-sqlite3 and requires CGO to be enabled at build
time.
The session identity is always per-run, even when the store is configured once on
the agent. That keeps tenant scoping explicit. ResourceID isolates
conversations that happen to share an ID.
Policies and approvals
Approval is a policy decision, not a model-invoked tool. A model cannot skip or
spoof the check.
opts := agent.RunOptions{
Policy: agent.Hooks{
OnBeforeTool: func(_ context.Context, req *agent.ToolRequest) (agent.Decision, error) {
if req.Spec.Annotations.Destructive {
return agent.Ask, nil
}
return agent.Allow, nil
},
},
Approver: agent.ApproverFunc(func(_ context.Context, req agent.ToolRequest) (bool, error) {
// Show req.Call and req.Spec to a human and return their decision.
return confirmWithUser(req.Call), nil
}),
}
response, err := assistant.GenerateWith(ctx, "Clean up the build directory.", opts)
The decisions are:
| Decision |
Effect |
agent.Allow |
Execute the tool. |
agent.Deny |
Skip the tool and report the denial to the model. |
agent.Ask |
Require the approver. Without one, the call is denied. |
agent.Terminate |
Abort the run. |
A full Policy also has BeforeModel and AfterModel hooks, which can reject
or observe model requests and responses. agent.PolicyChain composes policies in
order; agent.Hooks is the function-field implementation for the common case.
Agent defaults and run overrides
Behavior that should apply to every run belongs on agent.Config. A run
overrides it with RunOptions; unset values inherit the agent configuration.
temperature := 0.2
assistant, _ := agent.New(agent.Config{
// ...
Approver: approver,
Store: session.NewMemory(),
Budget: agent.Budget{MaxSteps: 16, MaxDuration: 10 * time.Minute},
Retry: agent.RetryPolicy{MaxAttempts: 3},
ToolTimeout: 30 * time.Second,
Temperature: &temperature,
})
// This run raises only the step limit. The duration cap, store, approver,
// retry policy, and tool timeout still apply.
response, err := assistant.Generate(ctx, "Analyze this repository.",
agent.WithMaxSteps(32),
agent.WithSession("review-1", "user-1"),
)
Precedence is package defaults, then agent.Config, then RunOptions. Budget
and RetryPolicy merge field by field, so overriding one field keeps the others.
Session is always per-run; an agent Store still requires a session. Sink and
Media stay per-run because they belong to a specific execution.
Useful defaults:
agent.DefaultMaxSteps is 8 when Budget.MaxSteps is zero.
agent.DefaultToolTimeout is 2 minutes.
RetryPolicy.MaxAttempts counts total attempts, including the first. Zero or
one disables retries.
(*Agent).ApplyAgentOptions applies the same layering to a RunOptions value.
The runtime calls it for every run, so custom execution engines can reuse it
instead of duplicating the merge rules.
Structured output
GenerateStructured constrains the response to a JSON Schema generated from T
and decodes it for you:
type WeatherReport struct {
City string `json:"city" description:"City name"`
Temperature float64 `json:"temperature_c" description:"Current temperature in Celsius"`
Conditions []string `json:"conditions" description:"Short condition labels"`
}
report, response, err := agent.GenerateStructured[WeatherReport](
ctx, assistant, "Report the weather in Tokyo.",
)
if err != nil {
log.Fatal(err)
}
fmt.Printf("%s: %.1f°C\n", report.City, report.Temperature)
The same behavior is available as a run option:
response, err := assistant.Generate(ctx, "Report the weather in Tokyo.",
agent.WithOutputSchema[WeatherReport](),
)
var report WeatherReport
err = response.Unmarshal(&report)
Response.Unmarshal tolerates a single Markdown JSON code fence around the
output. Use WithOutputSchema[T](opts...) with tool.SchemaOption values when
you need to customize schema generation. Providers that cannot enforce a strict
schema fail with llm.ErrUnsupported rather than silently relaxing the request;
the Anthropic adapter currently does not advertise strict JSON Schema support.
Subagents
Agent.AsTool exposes an agent as a typed tool. Composition is ordinary Go code:
researcher, _ := agent.New(agent.Config{
Name: "researcher",
Description: "Finds primary sources",
Instructions: "Find and cite primary sources.",
Model: model,
})
writer, _ := agent.New(agent.Config{
Name: "writer",
Instructions: "Draft an article using the researcher's findings.",
Model: model,
Tools: []tool.Tool{researcher.AsTool()},
})
Use AsToolWith to override the tool name or description, or to give the
subagent its own RunOptions:
researcher.AsToolWith(agent.AsToolConfig{
Name: "research",
Description: "Research a topic and return sources.",
Options: agent.RunOptions{Budget: agent.Budget{MaxSteps: 12}},
})
There is no sequential, parallel, or loop DSL in the core. Use goroutines,
errgroup, and ordinary functions.
Observability
Implement agent.Sink or pass agent.SinkFunc to receive run events without
affecting execution:
sink := agent.SinkFunc(func(event agent.Event) {
switch event := event.(type) {
case agent.TextDelta:
fmt.Print(event.Text)
case agent.ToolStart:
log.Printf("tool %s: %s", event.Call.Name, event.Call.Arguments)
case agent.ToolEnd:
log.Printf("tool %s finished with error: %v", event.Call.Name, event.Err)
}
})
response, err := assistant.Generate(ctx, "Summarize this repository.",
agent.WithSink(sink),
)
Events include RunStart, StepStart, MessageStart, TextDelta,
ThinkingDelta, ToolCallDelta, MessageEnd, ToolStart, ToolUpdate,
ToolEnd, and RunEnd. ToolStart/ToolEnd are paired, including for denied,
failed, or policy-aborted calls. ToolUpdate is reserved for tools and
schedulers that surface progress; the current runner does not emit it. Policies
observe and decide; sinks only observe. A panicking sink does not prevent other
sinks from receiving the event.
For metrics, wrap the seams instead: an llm.Model wrapper can record latency
and token usage, and a session.Store wrapper can record persistence failures.
Models and providers
| Provider |
Module |
Constructor |
Credentials |
| Google Gemini |
providers/google |
google.New |
GEMINI_API_KEY or GOOGLE_API_KEY |
| OpenAI Responses |
providers/openai |
openai.New |
OPENAI_API_KEY |
| OpenAI Chat Completions |
providers/openai |
openai.NewChatCompletion |
OPENAI_API_KEY |
| Anthropic Messages |
providers/anthropic |
anthropic.New |
ANTHROPIC_API_KEY |
| Deterministic mock |
providers/mockllm |
mockllm.New |
none |
import (
"github.com/ijaidev/gojent/providers/anthropic"
"github.com/ijaidev/gojent/providers/google"
"github.com/ijaidev/gojent/providers/openai"
)
gemini, err := google.New(ctx, google.Config{
Model: "gemini-2.5-flash",
APIKey: os.Getenv("GEMINI_API_KEY"),
})
gpt, err := openai.New(ctx, openai.Config{
Model: "gpt-5",
APIKey: os.Getenv("OPENAI_API_KEY"),
})
claude, err := anthropic.New(ctx, anthropic.Config{
Model: "claude-sonnet-4-5",
APIKey: os.Getenv("ANTHROPIC_API_KEY"),
})
Every adapter accepts extra request headers. OpenAI and Anthropic also accept a
custom base URL for OpenAI-compatible gateways, proxies, or local servers; Google
accepts a pre-configured ClientConfig or Client instead. Header maps are
copied at construction; HeaderFunc computes per-call headers from ctx when
the value must change between runs.
Capabilities are explicit. llm.Info reports limits, features, and pricing, and
the runner rejects a request the model cannot honor. If you configure reasoning,
vision, or structured output, check Features first or let the adapter return
llm.ErrUnsupported.
Extending
A custom model
Implement three methods:
type Model interface {
ModelID() string
Info() llm.Info
Generate(ctx context.Context, req *llm.Request) (*llm.Response, error)
}
Implement llm.Streamer as well to opt into incremental generation:
type Streamer interface {
Model
Stream(ctx context.Context, req *llm.Request) (llm.Stream, error)
}
Info must be accurate: the runner checks it before building a request instead
of probing for optional behavior.
A custom store
Implement Load and atomic Append. Return messages in chronological order,
isolate ResourceID, and deep-copy values if your backend reuses buffers. The
conformance suite in core/session/sessiontest
checks ordering, tenant isolation, atomic append, replay state, validation, and
cancellation:
func TestStore(t *testing.T) {
sessiontest.Run(t, func(t *testing.T) session.Store {
return newTestStore(t)
})
}
The same pattern is available for model adapters in
core/llm/llmtest, which checks that generation and
streaming agree on text, reasoning, tool calls, usage, and finish reasons.
Middleware
Wrap a seam instead of adding hooks to the core:
type loggingModel struct {
next llm.Model
}
func (m loggingModel) ModelID() string { return m.next.ModelID() }
func (m loggingModel) Info() llm.Info { return m.next.Info() }
func (m loggingModel) Generate(ctx context.Context, req *llm.Request) (*llm.Response, error) {
start := time.Now()
resp, err := m.next.Generate(ctx, req)
log.Printf("model=%s duration=%s err=%v", m.next.ModelID(), time.Since(start), err)
return resp, err
}
Because llm.Model is a small interface, wrappers compose without the runtime
knowing about them.
Repository layout
core/agent immutable agents, run options, policies, events
core/llm model contract, messages, streams, errors
core/tool typed tools, schemas, validation, results
core/session session identity, store contract, memory store
tools filesystem, command, web, and task tools
providers/anthropic Anthropic Messages adapter (separate module)
providers/google Gemini adapter (separate module)
providers/openai OpenAI Responses and Chat Completions adapter (separate module)
providers/mockllm deterministic test model
stores/sqlite SQLite store (separate module)
stores/postgres PostgreSQL store (separate module)
codjent sample coding agent (separate module)
examples runnable demonstrations
Development
The repository is a Go workspace with a root module and several optional
modules. go.work is intentionally not tracked; create it once after cloning.
See CONTRIBUTING.md for module, release, commit, and
pull-request workflow.
just workspace
Each module has its own justfile. The root recipes delegate to every module:
just test # unit tests
just vet # go vet
just build # go build
just lint # static analysis
just arch-check # module and package dependency boundaries
just tidy # go mod tidy
just frontend-check # rebuild codjent UI and verify committed assets
just check # formatting, tidy, vet, build, lint, architecture, tests, and frontend
Run a single module's recipe with just --justfile <dir>/justfile <recipe>, for
example:
just --justfile providers/google/justfile test
The PostgreSQL integration suite is opt-in:
GOJENT_POSTGRES_DSN='postgres://postgres:postgres@localhost:5432/gojent_test?sslmode=disable' \
just --justfile stores/postgres/justfile test-integration
Shared suites catch adapter drift:
core/llm/llmtest checks that generation and streaming
agree on text, reasoning, tool calls, usage, and finish reasons.
core/session/sessiontest checks ordering, tenant
isolation, atomic append, replay state, validation, and cancellation.
Every provider and store module includes the relevant suite. The PostgreSQL
store runs its conformance checks as part of the opt-in integration tests.
Versioning
The root module and each optional module are versioned independently. See
CHANGELOG.md for released changes to the root module; adapter
and codjent release notes belong with their own tags. Tag the root module as
vX.Y.Z and every submodule with its directory prefix, so go get can resolve
each one:
git tag v0.2.0 # root module
git tag providers/google/v0.2.0
git tag providers/openai/v0.2.0
git tag providers/anthropic/v0.2.0
git tag stores/sqlite/v0.2.0
git tag stores/postgres/v0.2.0
git tag codjent/v0.2.0
Optional modules require a released root module version in their go.mod. When
the root module changes, bump that requirement (and tidy) before tagging the
dependent modules, otherwise consumers resolve an older core.
Until v1, minor versions may contain breaking changes. Adapter modules follow the
same rule.
Non-goals
The core deliberately does not include:
- a workflow engine, graph DSL, or node editor;
- a UI or hosted service (codjent is an optional sample outside the core);
- a vector database or retrieval framework;
- provider-specific concepts in the core;
- mandatory third-party dependencies in the root module.
Optional features belong in separate modules that you fetch with go get.
License
Apache 2.0. See LICENSE.