Reference on core-agent

Providers

Mon, 01 Jan 0001 00:00:00 +0000

core-agent ships four model backends, all behind the same models.Provider interface. Pick one explicitly via model.provider in .agents/config.json or with the --provider CLI flag, or let env-based auto-detection pick.

Auto-detection

When model.provider is empty (the default), core-agent walks the environment in this order and picks the first match:

Vertex Gemini — fires when GOOGLE_GENAI_USE_VERTEXAI=true and GOOGLE_CLOUD_PROJECT is set
Gemini API — fires when GOOGLE_API_KEY or GEMINI_API_KEY is set
Anthropic — fires when ANTHROPIC_API_KEY is set

If none match, you get a clear error listing the env vars to set. Anthropic-via-Vertex is not auto-detected — it overlaps with Vertex Gemini in env vars, so you have to opt in explicitly with --provider anthropic-vertex or model.provider: "anthropic-vertex" in config.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

The `.agents/` directory

core-agent walks up from the working directory looking for a folder named .agents/, analogous to how git looks for .git. The first match wins. Everything core-agent reads or writes lives there:

.agents/
├── config.json # this file — provider, model, permissions, scope, telemetry, etc.
├── mcp.json # MCP server declarations (see MCP page)
├── skills/ # SKILL.md bundles (see Skills page)
└── sessions/ # one-shot transcripts; auto-written, safe to .gitignore

You don’t have to create .agents/ — without it, core-agent runs with built-in defaults and skips the project-specific bits (no transcripts, no MCP, no skills). It’s required only when you want to customize.

Built-in tools

Mon, 01 Jan 0001 00:00:00 +0000

The model-facing tool catalog core-agent registers by default, plus the optional lifecycle tools the runtime wires when the corresponding feature is enabled (checkpoints, ask, autonomous scheduling). For declaring third-party tools, see MCP servers. For writing your own tools from Go, see Library API.

The built-in catalog

Thirteen tools are registered by default. Each is configurable via the BuiltinTools struct in pkg/tools (library callers) or the --disable-tools flag / tools.disable config field (CLI users). Every call routes through the permission gate under the tool namespace — denying a tool by pattern keeps it from running even if it’s registered.

MCP servers

Mon, 01 Jan 0001 00:00:00 +0000

core-agent integrates with Model Context Protocol servers via ADK’s mcptoolset. Declare servers in .agents/mcp.json; core-agent spawns or connects to them at startup, namespaces their tools, and routes every tool call through the permission gate.

`mcp.json` schema

{
 "version": 1,
 "servers": {
 "filesystem": {
 "transport": "stdio",
 "command": "mcp-server-filesystem",
 "args": ["--root", "/tmp"],
 "env": { "LOG_LEVEL": "info" }
 },
 "github": {
 "transport": "http",
 "url": "https://api.githubcopilot.com/mcp/",
 "headers": { "Authorization": "Bearer ${env:GITHUB_TOKEN}" }
 }
 }
}

Top-level fields:

Field	Type	Notes
`version`	int	Schema version. Currently `1`.
`servers`	object	Map of `name` → `ServerSpec`. The `name` becomes the tool namespace prefix.

`ServerSpec`

Field	Required when	Notes
`transport`	always	`"stdio"` or `"http"`.
`command`	`transport: stdio`	Executable to spawn.
`args`	optional, stdio	Argv tail.
`env`	optional, stdio	Extra env vars; layered on top of the parent env. Values support `${env:NAME}` interpolation.
`url`	`transport: http`	Streamable HTTP endpoint.
`headers`	optional, http	Custom headers. Values support `${env:NAME}` interpolation — useful for `Authorization: Bearer ${env:TOKEN}`.
`auth`	optional, http	Selects an authentication strategy that manages tokens for you instead of static headers. See Authentication below.

Validation runs at config load time. A server that mixes transports (e.g. both command and url) is rejected with a clear error before the agent starts.

Context management

Mon, 01 Jan 0001 00:00:00 +0000

Long agent sessions hit two failure modes the model can’t recover from on its own:

The context window fills up. Every turn appends to the prompt; eventually the next turn errors out with “context window exceeded.”
Raw tool output bloats the parent. A 5,000-line file read, a 200KB URL fetch, a grep with hundreds of matches — each dumps that volume into the parent’s window even while it’s still working, slowing every subsequent turn and crowding out the actual task.

core-agent ships three mechanisms — designed together, deployed independently — to keep long sessions alive. All three are on by default. See docs/context-management-design.md for the full design rationale.

Skills

Mon, 01 Jan 0001 00:00:00 +0000

core-agent loads SKILL.md bundles from .agents/skills/<name>/. The schema mirrors Anthropic’s published skills format so existing skill bundles drop in directly.

Directory layout

.agents/
└── skills/
 ├── echo/
 │ └── SKILL.md
 ├── jira-triage/
 │ ├── SKILL.md
 │ └── examples/
 │ └── ticket.md
 └── data-export/
 ├── SKILL.md
 └── helpers/
 └── export.py

Each subdirectory of .agents/skills/ is one skill. A skill must contain a SKILL.md at its root; the directory name is the skill’s identifier (and what the agent invokes by). Other files in the directory are referenced from SKILL.md and loaded on demand.

Permissions

Mon, 01 Jan 0001 00:00:00 +0000

The permission gate is the central chokepoint consulted before every tool call. It enforces three things in order:

A built-in bash denylist that’s non-overridable (even yolo mode can’t run rm -rf /).
A path scope check for file tools — out-of-scope reads/writes either prompt the user or fail.
The mode + allow/deny patterns from .agents/config.json.

Modes

Mode	Behavior
`ask` (default)	Allowlisted calls pass automatically; everything else prompts the user via the configured `Prompter`. With no `Prompter`, prompts fail closed with a clear error.
`allow`	Only allowlisted calls pass. Everything else is rejected without prompting — useful for headless / automated runs.
`yolo`	All calls pass except those caught by the bash denylist or a deny-pattern. Use with care; intended for trusted local dev.

Set via .agents/config.json:

Attach TUI

Mon, 01 Jan 0001 00:00:00 +0000

core-agent-tui is the operator-facing terminal UI for attach-mode — the remote client for an agent running elsewhere (workstation, K8s pod, peer-registered fleet member). It ships as a separate binary so the default core-agent stays distroless-clean (no terminal-rendering deps land in production K8s images). See Configuration → attach for the listener-side config and the HTTP/SSE protocol it consumes.

For local interactive use, run core-agent directly — its in-process TUI is the default when stdin is a terminal. core-agent-tui is the remote client only.

Agent card

Mon, 01 Jan 0001 00:00:00 +0000

core-agent can publish a /.well-known/agent-card.json descriptor from its attach-mode listener so external discovery systems — most notably Google Cloud Agent Registry — can index the binary’s name, description, and skills without a parallel registration channel. The endpoint is opt-in: a binary built without the card config behaves exactly like today’s binary plus a card-shaped 404 at the well-known path.

The card is discovery metadata, not a transport promise. core-agent does not speak the A2A JSON-RPC transport — the url field on the card points at the attach listener, and an A2A client that POSTs JSON-RPC at it gets a 404. GCP Agent Registry, the actual consumer of this endpoint, only reads the card; it never drives the URL as A2A. If you need a non-A2A-shaped registration, GCP also supports NO_SPEC which doesn’t require a card at all — see the Agent Registry register-agents docs.

Web UI (--ui flag)

Mon, 01 Jan 0001 00:00:00 +0000

The --ui flag mounts the mast-web operator UI at /ui/* on the attach listener. One binary, one port, one auth boundary — the SPA shares the same TLS cert, bearer token, and CORS origin as the attach API endpoints, eliminating cross-origin configuration entirely. The agent serves the UI; no separate web server required.

This is one of four ways to deploy mast-web. The others (hosted SPA, container image, self-host tarball) live in go-steer/mast-web and don’t involve core-agent at all. Pick --ui when you want a single binary, an air-gapped deployment, or local-dev iteration.

Sessions and event log

Mon, 01 Jan 0001 00:00:00 +0000

By default, every agent.Agent uses ADK’s in-memory session service: conversation history is alive only for the process lifetime, and a crash loses everything. For audit logs, replay, crash-resume, or any cross-restart workflow, wire a durable backend via the eventlog package.

This page covers when to use durable sessions, how to enable them, and what the substrate gives you.

What you get

import (
 "github.com/glebarez/sqlite"
 "github.com/go-steer/core-agent/pkg/agent"
 "github.com/go-steer/core-agent/pkg/eventlog"
)

handle, err := eventlog.Open(ctx, sqlite.Open("sessions.db"))
if err != nil { /* ... */ }
defer handle.Close()

a, _ := agent.New(m,
 agent.WithEventLog(handle),
 agent.WithTools(myTools),
)

The *eventlog.Handle bundles two things every consumer wants:

Scion adapter

Mon, 01 Jan 0001 00:00:00 +0000

extras/scion-agent/ packages core-agent for Scion’s container runtime. It is the Go counterpart of Scion’s Python adk_scion_agent example — same lifecycle contract, built on the core-agent library.

The adapter is opt-in. The core library and bundled CLI work standalone; you only build scion-agent when you want to deploy core-agent as a Scion-managed agent.

What it adds on top of `core-agent`

--input <task> flag. Scion’s harness appends this when starting an agent with an initial task. From v1.3.0 the value is pushed onto the agent’s inbox via Agent.Inject before the main loop starts; the first turn then drains it as the first [Inbox] block.
Non-blocking inbox loop (v1.3.0+). A background goroutine reads stdin and pushes each line onto the agent’s inbox via Agent.Inject. The main loop waits on Agent.InboxArrived() and runs a turn with prompt "continue"; the per-turn drain prepends queued messages as an [Inbox] block. Messages arriving while a turn is in flight no longer block — they queue immediately and land on the next turn’s prompt. (Previously the binary scanned stdin between turns, so a 30-second tool call delayed every message by 30 seconds.)
Transient activity emission. On every agent / tool boundary the adapter writes thinking, executing, or working to $HOME/agent-info.json so Scion’s UI can render what’s happening live.
Sticky lifecycle states via a sciontool_status tool. The model invokes this tool to declare ask_user, blocked, task_completed, or limits_exceeded. The tool shells out to Scion’s sciontool binary so the hub gets notified.

Outside a Scion container (no sciontool on PATH, no writable $HOME) the lifecycle hooks degrade to no-ops, so the same binary is usable for local development.

Multi-session daemon

Mon, 01 Jan 0001 00:00:00 +0000

One core-agent daemon serves multiple concurrent sessions belonging to different users — each with its own identity, ACL, permission grants, instruction overlays, and audit attribution. Multi-session is opt-in and strictly backward-compatible: deployments that don’t enable it see identical single-user behavior.

This page covers when to turn it on, how to configure it, and what isolation guarantees the substrate gives you. Design background: docs/multi-session-design.md in the repo.

When to use it

The single-user “one process per user per pod” model is fine for personal interactive sessions and per-tenant pod-per-user K8s deployments. Reach for multi-session when one or more of these is true:

Reference on core-agent

Providers

Auto-detection

Configuration

The .agents/ directory

Built-in tools

The built-in catalog

MCP servers

mcp.json schema

ServerSpec

Context management

Skills

Directory layout

Permissions

Modes

Attach TUI

Agent card

Web UI (--ui flag)

Sessions and event log

What you get

Scion adapter

What it adds on top of core-agent

Multi-session daemon

When to use it

The `.agents/` directory

`mcp.json` schema

`ServerSpec`

What it adds on top of `core-agent`