Agency config file

To set options, add an agency.json file to your project root. The compiler searches upward from the file you're running until it finds this file.

I would suggest referring to this page as needed, instead of reading it all the way through.

The basics

{
  "verbose": false,
  "logLevel": "info",
  "outDir": "./dist"
}

• verbose — extra logging during compilation.
• logLevel — "debug", "info", "warn", or "error".
• outDir — where compiled code goes (next to Agency source by default).

LLM client

This is where you set your default model, provider, and API keys.

{
  "client": {
    "defaultModel": "claude-fable-5",
    "defaultProvider": "anthropic",
    "apiKey": {
      "openAi": "sk-...",
      "anthropic": "sk-ant-..."
    },
  }
}

Option	Description
defaultModel / defaultProvider	Used when a llm() call doesn't specify its own.
apiKey	Keys for openAi, google, anthropic, ollama, openRouter, deepInfra, liteLlm, and openAiCompat.
baseUrl	Needed if you're using a provider that provides an endpoint compatible with the OpenAI API, such as openRouter, deepInfra, liteLlm and others.
maxToolResultChars	Caps how much of a single tool result the model sees (the full value still reaches your code). Default 100000; 0 disables it. Keeps a chatty tool from blowing the context window.
providerModules	Paths to custom smoltalk provider modules (e.g. a local model via smoltalk-llama-cpp).
modelAliases / modelsDir	Short-name aliases and the cache directory for local models.

Agency uses Smoltalk for its LLM client.

Type checking

The typechecker is on by default.

{
  "typechecker": {
    "enabled": true,
    "strict": true,
    "strictTypes": true,
    "undefinedFunctions": "warn"
  }
}

Option	Description
enabled	Run the type checker and print warnings. Defaults to true.
strict	Type errors become fatal. Defaults to true.
strictTypes	Untyped variables are errors.
undefinedFunctions / undefinedVariables	"silent", "warn", or "error" for undefined functions or variables. Both default to "warn".
strictMemberAccess	Guards against accessing a member that only exists on some branches of a union. For example, if you had a Result type, and you tried to access result.value (which only exists on Success), that would be an error. Default "error".
matchExhaustiveness	Flags a match over a closed type that doesn't cover every case. For example, if you were matching over a variable with a union type like "success"
definiteReturns	Flags a function that has a return type set, but not all of its code paths return a value. Default "error".

Observability and logging

Turns on logging. See Observability for details.

{
  "observability": true,
  "log": {
    "logFile": "log.jsonl"
  }
}

Memory

Enable the memory layer so agents can store and recall facts across runs. Setting this makes std::memory usable and lets llm({ memory: true }) inject relevant facts. See Memory for details.

{
  "memory": {
    "dir": "./.agency-memory",
    "autoExtract": { "interval": 5 },
    "compaction": { "trigger": "token", "threshold": 8000 }
  }
}

Option	Description
dir	Where memory JSON files live (required if you use memory).
model	Model used for extraction, compaction, and recall.
autoExtract.interval	How many turns to wait before running an auto-extraction on message history. Default 5.
compaction	Controls when a conversation gets compacted. When the thread crosses threshold, Agency extracts facts from the older messages in the conversation, summarizes them with an LLM, and replaces them with a single summary message. Roughly the older half of the conversation is compacted. Use trigger to pick the metric: either "token" (estimated at roughly 4 characters per token) or "messages" (raw message count). Defaults to trigger: "token" and threshold: 50000.
embeddings.model	Embedding model for semantic recall.

Debugging and tracing

{
  "trace": true
}

Option	Description
debugger	Auto-inserts a breakpoint before every step.
instrument	Emit per-step instrumentation (default true). Set false to shed the overhead when you don't need tracing.
trace / traceFile / traceDir	Write execution checkpoints to a .trace file.
distDir	Directory of pre-compiled JS the debugger imports instead of compiling on the fly.

Runtime limits

Safety guards that stop a program from running away.

{
  "maxCallDepth": 2048,
  "maxToolCallRounds": 10,
  "checkpoints": { "maxRestores": 100 }
}

Option	Description
maxCallDepth	The runaway-recursion guard. Default 2048; raise it for legitimately deep recursion.
maxToolCallRounds	How many times the LLM can loop between calling tools and reacting to their output before Agency halts it. Default 10.
checkpoints.maxRestores	Cap on how often one checkpoint can be restored before it errors out. Default 100.

Testing and coverage

{
  "test": { "parallel": 4 },
  "coverage": {
    "threshold": 80,
    "perFileThreshold": 60,
    "exclude": ["examples/**"]
  }
}

Option	Description
test.parallel	Number of test files to run at once. Default 1.
coverage.threshold / coverage.perFileThreshold	Minimum coverage percentages; agency coverage report fails below them.
coverage.outDir	Where coverage data lands.
coverage.exclude	Which files to skip, as glob patterns (e.g. ["examples/**"]).

Eval and optimize

Configuration for the agency eval and agency eval optimize commands.

{
  "eval": {
    "runsDir": "./eval-runs",
    "optimize": {
      "goal": "Maximize accuracy",
      "graders": "./graders.ts",
      "validation": { "split": 0.2 }
    }
  }
}

Option	Description
runsDir	Where agency eval saves its run artifacts. Default runs.
optimizeRunsDir	Where agency eval optimize saves its artifacts. Defaults to an optimize subdirectory inside runsDir.
optimize.goal	The optimization objective.
optimize.graders	Path to a TS grading module.
optimize.optimizer	A built-in optimizer name or a path to your own module.
optimize.validation	A validation inputs file and/or a split fraction held out for validation.

Docs, packing, and the log viewer

Odds and ends for other commands.

{
  "doc": { "outDir": "docs", "baseUrl": "https://github.com/me/repo" },
  "pack": { "format": "esm", "target": "node20" },
  "viewer": { "slowMs": 5000, "expensiveUsd": 0.01 }
}

Option	Description
doc	Output directory and source-link base URL for agency doc.
pack	Options for agency pack: output format ("esm" or "cjs"), esbuild target (e.g. "node20"), and external. external is an array of package names to exclude from the bundle and import at runtime instead (for packages that can't be bundled, like native addons). Anything marked external must already be installed wherever the bundle runs.
viewer	Color thresholds for agency logs view: slowMs and fastMs for durations, expensiveUsd for cost.

References

• Full list of options.