Skip to content
Documentation
Getting started

Getting started

Getting started

Install

Requires Go 1.26 or newer.

As a CLI 

go install github.com/go-steer/core-agent/cmd/core-agent@latest

The binary lands in $(go env GOBIN) (or $GOPATH/bin if GOBIN is unset). Make sure that’s on your $PATH.

As a library 

go get github.com/go-steer/core-agent

Then import "github.com/go-steer/core-agent/agent" (and the relevant submodules).

First run — pick a provider

You need credentials for at least one model backend. Skip the sections you don’t have keys for.

Gemini API (fastest to set up)

Get a key at aistudio.google.com. Then:

export GEMINI_API_KEY=...   # or GOOGLE_API_KEY — either works
core-agent -p "what's the capital of France?"

Auto-detection picks the Gemini provider when GEMINI_API_KEY or GOOGLE_API_KEY is set and no other provider is configured.

Vertex AI (Gemini)

If you have GCP infrastructure already:

gcloud auth application-default login
export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT=my-gcp-project
export GOOGLE_CLOUD_LOCATION=us-central1
core-agent -p "what's the capital of France?"

Anthropic / Claude (first-party)

Get a key at console.anthropic.com.

export ANTHROPIC_API_KEY=...
core-agent --provider anthropic --model claude-opus-4-7 -p "what's the capital of France?"

Anthropic / Claude via Vertex AI

If you’d rather use your existing GCP credentials and billing for Claude:

gcloud auth application-default login
export ANTHROPIC_VERTEX_PROJECT_ID=my-gcp-project   # or GOOGLE_CLOUD_PROJECT
export CLOUD_ML_REGION=us-east5                     # or GOOGLE_CLOUD_LOCATION
core-agent --provider anthropic-vertex --model claude-opus-4-7 -p "what's 2+2?"

Note: Vertex’s Claude model IDs sometimes carry a @version suffix (e.g. claude-opus-4-5@20251101). If the bare alias doesn’t resolve, check the Vertex Model Garden for the current ID.

See the Providers reference for full details on each backend.

Multi-turn REPL

Drop the -p flag to enter the stdin REPL. Conversation history is preserved across turns automatically.

$ core-agent
core-agent REPL — /exit or Ctrl-D to quit
> Remember the number 73.
Got it — I'll remember 73.
> What number did I just give you?
73.
> /exit

Built-in commands: /exit, /quit, EOF (Ctrl-D).

Layer in a project — the .agents/ directory

core-agent walks up from the current working directory looking for a folder named .agents/, much like git looks for .git. It’s the project-level home for everything core-agent reads or writes:

your-repo/
├── .agents/
│   ├── config.json          # provider, model, permissions, etc.
│   ├── mcp.json             # MCP server declarations
│   ├── skills/              # SKILL.md bundles
│   │   └── echo/SKILL.md
│   └── sessions/            # one-shot transcripts (auto-written)
└── AGENTS.md                # system prompt prefix (project-scoped)

A minimal config.json:

{
  "version": 1,
  "model": {
    "provider": "anthropic",
    "name": "claude-opus-4-7"
  }
}

core-agent will pick up everything in .agents/ automatically — no flags needed. See the Configuration reference for the full schema.

Pin a system prompt with AGENTS.md

Drop a file named AGENTS.md at your repo root and core-agent prepends its contents to every system prompt:

You are a helpful assistant for the Acme widget team.
Answer in plain prose. Do not use bullet lists unless explicitly asked.

Fallback chain: AGENTS.md → CLAUDE.md → GEMINI.md (first match wins). User-global memory at ~/.core-agent/AGENTS.md is concatenated before the project file.

What to read next

  • Providers — full reference for each model backend, env vars, and gotchas
  • Configuration — every field of .agents/config.json
  • MCP servers — declarative third-party tool integration
  • Skills — Claude-compatible SKILL.md bundles
  • Permissions — gating tool calls
  • Library API — using core-agent from your own Go code
Providers