cortex

Cortex: AI agent orchestration framework for Go

Cortex is an open-source Go library for building LLM agents. You define an agent from a system prompt, tools and, if you want more structure, skills, personality traits, behaviors and personas, and Cortex runs it through a ReAct loop with tool calling, conversation memory, human-in-the-loop checkpoints and runs that suspend and resume. Several agents can work together through sequential, parallel, router, hierarchical and debate orchestration, or message each other directly. Everything is scoped to the tenants or workspaces your app defines, stored in PostgreSQL, SQLite or MongoDB, and works standalone or as a Forge extension.

Documentation · Quick start · Features · Human model · Orchestration · Forge · FAQ

Quick start

You need Go 1.26 or later and an OpenAI API key. Cortex talks to models through an llm.Client, and the adapter that ships with it wraps a Nexus gateway, so you add Nexus and its OpenAI provider too:

go get github.com/xraph/cortex@latest
go get github.com/xraph/nexus@latest github.com/xraph/nexus/providers/openai@latest
go get github.com/xraph/grove/drivers/sqlitedriver@latest

Save this as main.go:

package main

import (
	"context"
	"fmt"
	"log"
	"os"
	"time"

	"github.com/xraph/grove"
	"github.com/xraph/grove/drivers/sqlitedriver"
	_ "github.com/xraph/grove/drivers/sqlitedriver/sqlitemigrate" // registers the SQLite migration executor
	"github.com/xraph/nexus"
	"github.com/xraph/nexus/providers/openai"
	"github.com/xraph/nexus/tenant"

	"github.com/xraph/cortex"
	"github.com/xraph/cortex/agent"
	"github.com/xraph/cortex/engine"
	"github.com/xraph/cortex/id"
	"github.com/xraph/cortex/llm"
	nexusllm "github.com/xraph/cortex/llm/nexus"
	sqlitestore "github.com/xraph/cortex/store/sqlite"
)

func main() {
	// Every stored row belongs to a scope you define. Cortex refuses to
	// read or write without one.
	ctx := cortex.WithScope(context.Background(), cortex.Scope{
		Levels: []cortex.Level{{Key: "workspace", Value: "acme"}},
	})

	// Storage: SQLite through Grove.
	drv := sqlitedriver.New()
	if err := drv.Open(ctx, "cortex.db"); err != nil {
		log.Fatal(err)
	}
	db, err := grove.Open(drv)
	if err != nil {
		log.Fatal(err)
	}
	st := sqlitestore.New(db)
	if err := st.Migrate(ctx); err != nil {
		log.Fatal(err)
	}

	// The model: OpenAI behind a Nexus gateway.
	gw := nexus.New(nexus.WithProvider(openai.New(os.Getenv("OPENAI_API_KEY"))))
	if err := gw.Initialize(ctx); err != nil {
		log.Fatal(err)
	}
	defer gw.Shutdown(ctx)

	// Every model call goes out under a Nexus tenant. This one lives in
	// the gateway's in-memory store, so it's made fresh on each start.
	acme, err := gw.Tenants().Create(ctx, &tenant.CreateInput{Name: "Acme", Slug: "acme"})
	if err != nil {
		log.Fatal(err)
	}
	toAcme := func(context.Context, cortex.Scope) (string, error) { return acme.ID.String(), nil }

	// A tool the agent can call.
	clock := llm.Tool{
		Name:        "current_time",
		Description: "Returns the current time in UTC.",
		Parameters:  map[string]any{"type": "object", "properties": map[string]any{}},
	}
	tellTime := func(_ context.Context, _ cortex.Invocation) (string, error) {
		return time.Now().UTC().Format(time.RFC3339), nil
	}

	eng, err := engine.New(
		engine.WithStore(st),
		engine.WithLLM(nexusllm.New(gw, nexusllm.WithTenant(toAcme))),
		engine.WithTool(clock, tellTime),
	)
	if err != nil {
		log.Fatal(err)
	}

	err = eng.CreateAgent(ctx, &agent.Config{
		ID:           id.NewAgentID(),
		Name:         "assistant",
		SystemPrompt: "You are a concise assistant. Use your tools when they help.",
		Model:        "gpt-4o-mini",
		MaxSteps:     5,
	})
	if err != nil {
		log.Fatal(err)
	}

	r, err := eng.RunAgent(ctx, "assistant", "What time is it in UTC right now?", nil)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(r.State, r.StepCount, r.TokensUsed)
	fmt.Println(r.Output)
}

Run it:

go mod tidy
OPENAI_API_KEY=sk-... go run .

The model sees current_time, calls it, gets the timestamp back from your handler and answers with it. You'll see the run's final state, how many steps it took and the tokens used, then the answer. The run, every step and the tool call are now rows in cortex.db, so eng.ListSteps and eng.ListToolCalls can show you exactly what happened. Run it a second time and CreateAgent fails, because an agent named assistant already exists in that scope. Delete cortex.db or use GetAgentByName first.

If you leave out WithLLM, RunAgent still works, in an echo mode that's handy for wiring tests.

The Nexus adapter

The adapter refuses to send a call without a Nexus tenant, which is why the quick start makes one. In a real host you map your scope to its tenant with nexusllm.WithTenant, or set pipeline.WithTenantID on the context next to the scope. Each call is recorded in Nexus's usage with your scope levels and the run and agent behind it, so you can see what a run cost. nexusllm.WithProvider pins the provider a workspace picked, and nexusllm.WithSamplingUnsupported tells the adapter which models reject temperature (Claude 5.5 does, and the adapter already knows those ids).

Thinking models keep their signed thinking between turns, through approvals and reclaims, but it never reaches conversation memory. A turn whose text your publication gate redacted loses its thinking blocks when it is replayed to the model (set the Nexus Anthropic provider's anthropic.WithThinkingBlockBinding("drop_block") if you want that explicit). The thinking blocks are the model's unredacted output, and they sit that way in progress snapshots and continuations. A Nexus guard that blocks a response stops the run with safety_block and no tool from that step runs. Configuration has the details.

The Weave adapter

Every knowledge search runs under a Weave tenant, taken from the run's scope with weaveknowledge.WithTenant (the default is the scope's first level). A run only reads its own tenant's collections, plus any read-only ones you list with weaveknowledge.WithShared, such as your product docs. A call with no tenant fails before Weave is asked. Under the Forge extension, pass these with extension.WithWeaveOptions. Configuration has the details.

The Shield adapter

safety/shield screens what a run reads and writes with a Shield engine, and it can gate tool calls too. It's your safety scanner and your publication gate. Each scan runs under a Shield tenant taken from the run's scope (shieldsafety.WithTenant, first scope level by default) and the app you name with shieldsafety.WithApp, using the profile in the agent's shield_profile guardrail. When the adapter is your publication gate (shieldsafety.EngineOption and the Forge extension install it as both), tool results, tool errors and retrieved knowledge go in as untrusted, so Shield quotes them before the model reads them. A scan that can't run (no tenant, no profile, input too large) blocks the content. It never lets it through.

shieldsafety.NewToolAuthorizer puts Shield's tool-call scan under your own cortex.ToolAuthorizer. Your authorizer answers first, and Shield can then deny the call or ask a person to approve it, but it can't allow a call you refused. Under the Forge extension, pass adapter options with extension.WithShieldOptions. Configuration and Authorization have the details.

Why Cortex?

Calling a chat API in a loop gets you an agent for a demo. Then you need the run history in a database, a person to approve a risky tool call, a run that can wait a day for an external result without holding a goroutine, and a guarantee that one customer's agents never read another's memory. Cortex handles those parts so your code only describes the agents and their tools.

Scope comes first

Cortex has no built-in tenant. You decide the levels, in order, and put them on the context:

ctx = cortex.WithScope(ctx, cortex.Scope{
	Levels: []cortex.Level{
		{Key: "org", Value: "acme"},
		{Key: "project", Value: "support"},
	},
})

Store methods read it back and return cortex.ErrNoScope when it's empty, so a scope you forgot to pass fails loudly and never becomes a query across every tenant. Lists match by prefix: a context scoped to org=acme sees every project under it. Keep the order of your levels stable between releases, because each position maps to an indexed column.

The human model

You can run an agent on a plain system prompt. When you want reusable structure, Cortex gives you these building blocks, each with its own store and CRUD methods on the engine:

Point an agent at a persona with PersonaRef, or list skills, traits and behaviors inline with InlineSkills, InlineTraits and InlineBehaviors. RunOverrides lets one run swap the model, persona, tools or session without changing the stored agent, and CloneAgent and ClonePersona copy one under a new name.

Tools

engine.WithTool takes a definition and a handler, and you write the JSON Schema yourself. You don't have to. The tool package builds a tool from a Go function over a struct, generates the schema from the struct's tags and checks every call against it before your function runs:

type ListInput struct {
	Project string `json:"project" jsonschema:"the project id"`
	Limit   int    `json:"limit,omitempty"`
}

eng, err := engine.New(
	engine.WithStore(st),
	tool.Register("list_services", "List the services in a project.",
		func(ctx context.Context, inv cortex.Invocation, in ListInput) ([]string, error) {
			return lookup(ctx, inv.Scope, in.Project, in.Limit)
		},
		tool.RetrySafe(),
	),
)

A call with a wrong type, a missing field or an argument the struct doesn't declare fails before your code sees it, and the model reads the error and can try again. tool.RetrySafe() says the tool can run twice without harm, which matters when a run is reclaimed after its worker died (see below). For a tool you registered with engine.WithTool, use engine.WithToolRetrySafe("name").

Already have an MCP server? The mcpbridge module turns its tools into cortex tools. You connect the *mcp.ClientSession, and mcpbridge.EngineOptions(ctx, cs, mcpbridge.Options{Prefix: "github_"}) gives you the engine options. Tools the server marks read-only come in as retry-safe, the rest don't. It's a separate module, so the engine itself never depends on the MCP SDK. Typed tools and MCP tools have the details.

Runs, checkpoints and suspension

RunAgent returns the finished *run.Run. StreamAgent sends StreamEvents on a channel as the run goes: run_started, step, tool_call, token, checkpoint, safety_block, suspended, done and error.

A run pauses in two cases. Your ToolAuthorizer returns ErrRequiresApproval for a call, which creates a checkpoint that someone resolves with eng.ResolveCheckpoint. Or the model calls a tool you registered with WithExternalTool, and the run suspends until you call eng.Resume(ctx, runID, engine.ResumeInput{ToolResults: ...}). A suspended run is a stored row, not a blocked goroutine, so it survives a restart. WithSuspensionTTL sets the default deadline for a pause, and an approval or an external tool can bring a shorter one of its own. Zero only drops the default; the sweeper keeps running for calls with their own deadline. plugin.RunSuspended fires on every pause, which is where you tell somebody a decision is waiting.

You don't have to continue a run inside the request that answered it. eng.DecideCheckpoint records a decision and eng.ProvideResults records external results, and both return straight away with the run ready. Queue a job from the plugin.RunReady hook and call eng.ContinueRun(ctx, runID) in it, on any replica. The run makes its tool calls as the principal that started it, which you give the engine a way to store with engine.WithPrincipalCodec.

Runs can also survive the worker that was running them, once you turn leasing on with engine.WithRunLease(60*time.Second). It's off by default, and then Stop lets every run finish, as v1.9.0 did. With it on, every run on the built-in stores holds a lease and saves its progress at each step. If the worker dies, or Stop hands the run off, the run becomes reclaimable and plugin.RunReclaimable fires. Nothing in cortex continues it for you: your job calls the same ContinueRun, which carries on from the last saved step, so only turn leasing on once RunReady and RunReclaimable both queue that job. A tool call that was in flight runs again only if the tool is retry-safe. Otherwise the run ends incomplete with cortex.ErrEffectUncertain, because nobody can say whether the call did anything. Runs covers the states and the reclaim rules.

Multi-agent orchestration

You store an orchestration.Config with a strategy and the agents taking part, then run it by name whenever you need it:

err := eng.CreateOrchestration(ctx, &orchestration.Config{
	Name:     "review",
	Strategy: orchestration.StrategySequential,
	Participants: []orchestration.Participant{
		{AgentName: "drafter"},
		{AgentName: "editor"},
	},
})
// ...
result, err := eng.RunOrchestration(ctx, "review", "Write release notes for v1.7")

Participants share a blackboard with the roster and earlier work. For agents that talk without a fixed plan, the a2a bus sends FIPA-ACL style messages between them: fire-and-forget sends, a mailbox, and an ask that suspends the asking run until a peer replies. Turn it on with engine.WithA2A. The a2aremote module speaks the Agent2Agent protocol over JSON-RPC, REST and SSE for agents in other services, though it isn't tagged yet.

Storage

Every store filters reads by the first three scope levels only. Levels past the third are saved with the row, in scope_extra and in the canonical scope string, but no query matches on them, so two scopes that differ only below the third level read each other's rows. Keep your scopes to three levels.

Call Migrate(ctx) once before you use a store, or let the Forge extension do it for you on start. SQLite migrations need the executor from github.com/xraph/grove/drivers/sqlitedriver/sqlitemigrate, so import it for its side effect, as the quick start does. On MongoDB, saving or clearing a conversation writes the messages and the session's counters in one multi-document transaction, and a standalone mongod can't run transactions, so every conversation write fails against one.

Use it with Forge

The extension module registers Cortex as a Forge extension. It reads config from extensions.cortex (or cortex), takes its store from a *grove.DB in the container, wires in the Nexus, Shield, Weave and Sentinel services when they're registered (each one is skipped when it isn't), builds the engine and provides *engine.Engine. Start runs migrations.

go get github.com/xraph/cortex/extension@latest github.com/xraph/cortex/api@latest

import (
	"github.com/xraph/forge"
	"github.com/xraph/cortex/api"
	"github.com/xraph/cortex/engine"
	cortexext "github.com/xraph/cortex/extension"
)

app := forge.NewApp(forge.AppConfig{
	Name:        "agents",
	HTTPAddress: ":8080",
	Extensions: []forge.Extension{
		cortexext.New(
			cortexext.WithRoutes(func(eng *engine.Engine, r forge.Router) cortexext.RouteSet {
				return api.New(eng, r)
			}),
		),
	},
})

The extension mounts no HTTP routes by itself. The REST handlers live in the separate api module so you only compile them when you want them, and WithRoutes mounts them under /cortex by default. Leave it out and you still get the engine in the container and the dashboard contract.

The REST module doesn't check who's calling unless you give it an api.Authorizer with api.WithAuthorizer. That interface is asked about every route before it runs, and it names the person behind a checkpoint decision. Without one, any caller that reaches the router can use every route and decided_by on a checkpoint is whatever the caller wrote, so run it that way only when every caller is trusted equally.

extensions:
  cortex:
    base_path: /cortex
    default_model: smart
    default_max_steps: 25
    default_max_tokens: 4096
    default_temperature: 0.7
    default_reasoning_loop: react
    run_concurrency: 0      # runs at once in this process; 0 is no limit
    shutdown_timeout: 30s
    grove_database: ""      # a named grove.DB; empty uses the default one
    disable_routes: false
    disable_migrate: false

Those are the defaults. default_model is smart, which only means something if your gateway has an alias with that name. In code you have WithStore, WithGroveDatabase, WithEngineOption, WithExtension, WithConfig, WithBasePath, WithDisableMigrate, WithRequireConfig, WithDashboard and WithoutAutoAdapters. Anything you pass with WithEngineOption or WithStore wins over the config and over the services the extension finds in the container.

Lifecycle hooks

You write a hook as a plain value that implements any of the 21 small interfaces in plugin, and you register it with engine.WithExtension. They cover runs and steps (OnRunStarted, OnStepCompleted), tools (OnToolCalled, OnToolFailed, OnToolDenied), the human model (OnPersonaResolved, OnBehaviorTriggered, OnCognitivePhaseChanged), checkpoints, orchestration and handoffs, agent messages, and shutdown. audit_hook turns them into an audit trail for Chronicle.

Tracing and metrics

Every run is traced. A run is a run agent span, with a span per step, per tool call and per publication check under it, and the model call, store queries and safety scans from Nexus, Grove and Shield nest inside. The engine also records its own metrics: runs finished by state and stop reason, pass latency, steps, tool calls by kind, publication checks, suspensions, orchestrations and agent-to-agent deliveries. Every label is a closed set, and no prompt, tool argument, model output or agent name ever reaches a span or a label.

In a Forge app that's all on already; you'll find the metrics on /_/metrics as forge_cortex_*. Outside Forge, set an OpenTelemetry tracer provider and pass engine.WithMetrics. The observability page lists every span and series. The old observability metrics plugin is deprecated and records nothing now.

Modules

Documentation

A few newer pages are in the repo but not on the site yet: tool authorization, suspension, sessions, agent messaging, remote agents, typed tools and MCP tools. The Go API is on pkg.go.dev.

FAQ

How do I build an AI agent with tools in Go?

Register each tool with engine.WithTool(def, handler), where def is an llm.Tool with a JSON Schema for its arguments and handler returns the result as a string. Give the engine an llm.Client, create an agent, and call RunAgent. The quick start does exactly that.

Which LLM providers does Cortex support?

Any provider you can reach through an llm.Client. The bundled llm/nexus adapter goes through a Nexus gateway, which covers OpenAI, Anthropic, Gemini, Bedrock, Ollama and the rest of Nexus's providers. For anything else, implement Complete and CompleteStream yourself.

Can a person approve a tool call before it runs?

Yes. Return cortex.ErrRequiresApproval from your ToolAuthorizer's Authorize for that call. The run pauses, a checkpoint holds the call, and eng.ResolveCheckpoint with the decision lets it continue.

Can I use Cortex without Forge?

Yes. The root module doesn't import Forge at all. Only api and extension do, and they're separate modules.

Does Cortex need a database?

It needs a store.Store. SQLite is enough to get going, and PostgreSQL or MongoDB suit a deployment with more than one process.

Contributing

Issues and focused pull requests are welcome. Open an issue first for anything large.

git clone https://github.com/xraph/cortex.git
cd cortex
GOWORK=off go build ./...
make test     # root module
make lint     # golangci-lint in every module
cd extension && GOWORK=off go test -race -count=1 ./...

Only make lint walks every module. Test a sub-module from its own directory. The Postgres and Mongo store tests start containers through testcontainers and skip without Docker, so run with -v to see whether they ran. Skip make build, make run and make dev, which need a cmd/cortex that doesn't exist. AGENTS.md has the CI jobs, the scope rules for new store methods and the release steps. Commits follow Conventional Commits with a scope, as in fix(engine): ....

License

MIT. See LICENSE.

Cortex is part of the forgery stack built on Forge, by Rex Raphael and contributors.