Skip to main content
agentctl is the interactive REPL for Agent SDK for Go. Type prompts and receive agent responses. It uses the same SDK as your application code and supports both in-process and Temporal runtimes via a YAML config file.
agentctl is not the Go library. Install the SDK with go get github.com/agenticenv/agent-sdk-go. Install agentctl separately — download a release binary or build from source.

​
Install agentctl

Pre-built binaries for Linux, macOS, and Windows (amd64 and arm64) are on GitHub Releases.
  1. Open the latest release
  2. Download the archive for your platform from Assets
  3. Extract and add agentctl to your PATH

​
Option 2 — Build from source

make build
./cmd/bin/agentctl

# Or install to $GOPATH/bin:
make install
agentctl -config cmd/config.yaml

​
Option 3 — Run without building (development)

From a cloned repository: 
go run ./cmd
Compiles and runs on each invocation — useful during development.

​
Quick start

# 1. Copy the sample config
cp cmd/config.sample.yaml config.yaml
# Edit config.yaml — set llm.apiKey or use AGENT_LLM_APIKEY

# 2. Run the CLI
agentctl -config config.yaml
If you use a release binary without cloning the repo, copy config.sample.yaml from the release assets into your working directory. Type prompts at the > prompt. Enter exit, quit, or bye to end the session.

​
Configuration file

FilePurpose
cmd/config.sample.yamlTemplate — safe to commit
cmd/config.yamlYour config — gitignored, copy from sample
Run with a custom path: 
agentctl -config /path/to/config.yaml

​
Runtime selection

Set runtime in config.yaml:
ValueBehavior
local (default)In-process — no Temporal server required
temporalDurable execution — requires a running Temporal server
Override per invocation: 
AGENT_RUNTIME=temporal agentctl -config config.yaml

​
Minimal config.yaml

runtime: local

llm:
  provider: openai
  apiKey: ""           # prefer AGENT_LLM_APIKEY env var
  model: gpt-4o
  baseURL: https://api.openai.com/v1

temporal:
  host: localhost
  port: 7233
  namespace: default
  taskQueue: agent-sdk-go

logger:
  level: info
  output: logs/agent.log
  format: json

​
Environment variables

Environment variables override config file values. Prefer them for secrets.
VariableDescription
AGENT_RUNTIMElocal or temporal
AGENT_TEMPORAL_HOSTTemporal server host
AGENT_TEMPORAL_PORTTemporal gRPC port
AGENT_TEMPORAL_NAMESPACETemporal namespace
AGENT_TEMPORAL_TASKQUEUETask queue name
AGENT_LLM_PROVIDERopenai, anthropic, or gemini
AGENT_LLM_APIKEYLLM API key
AGENT_LLM_MODELModel name
AGENT_LLM_BASEURLOptional base URL for OpenAI-compatible proxies
AGENT_LOGGER_LEVELerror, warn, info, debug
AGENT_LOGGER_OUTPUTLog file path, stdout, or stderr
export AGENT_LLM_APIKEY=sk-your-key
export AGENT_LLM_PROVIDER=openai
export AGENT_LLM_MODEL=gpt-4o
agentctl -config config.yaml

​
MCP servers (optional)

Add mcp.servers entries to config.yaml to connect MCP tool servers. When at least one server is enabled, the CLI registers WithMCPConfig and AutoToolApprovalPolicy so MCP tools run without per-call approval in the REPL. 
mcp:
  servers:
    - enabled: true
      name: filesystem
      transport: stdio
      command: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
Each entry supports: enabled, name, transport (stdio or streamable_http), command/args (stdio) or url/bearer_token (HTTP), and optional timeout_seconds, retry_attempts, allow_tools, block_tools. See cmd/config.sample.yaml for HTTP transport, OAuth, and tool filter examples.

​
SDK vs CLI

SDK (library)CLI (agentctl)
Installgo get github.com/agenticenv/agent-sdk-go@latestDownload release binary or make build
UseImport pkg/agent in your Go applicationInteractive REPL from the terminal
ConfigGo code — NewAgent(...) optionsYAML file + env vars
Both are published from the same repository. Pin the SDK version in your go.mod; pin the CLI by downloading the matching release tag.

​
Logging

agentctl prints only user prompts and agent responses on the console. Internal SDK logs go to a file.
  • Default: cmd/logs/agent.log (gitignored)
  • Override: logger.output in config or AGENT_LOGGER_OUTPUT

Quickstart

Build an agent in your own Go application

Configuration

All SDK options the CLI uses under the hood

MCP

Connect MCP servers programmatically

Running Examples

Run SDK examples from the repository