Agency config file

To set options, add an agency.json file to the directory you run Agency from.

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

Local overrides

Put settings you don't want to commit in agency.local.json, next to agency.json. Agency merges the two files, and the local file wins. Add agency.local.json to your .gitignore.

// agency.json
{ "log": { "host": "https://statelog.example.com", "projectId": "team" } }

// agency.local.json
{ "log": { "projectId": "my-project" } }

With these files, Agency logs to https://statelog.example.com under the project my-project. agency deploy reads the same settings, so it deploys to my-project.

Agency merges the files with these rules:

1. Objects merge key by key.
2. An array in the local file replaces the array in agency.json.
3. Any other value in the local file replaces the value in agency.json.

The fields in this table are exceptions. A value at one of these paths replaces the matching value in agency.json whole. * stands for any name.

Path	Why
mcpServers.*	A server's fields depend on each other. Mixing two servers can change how Agency connects to it.
client.modelAliases.*	An alias's hash and companion models belong to its own model.

For example, if both files define an MCP server named search, Agency uses the one in agency.local.json. Servers that only agency.json defines are still used.

To see the config Agency will use, run agency config show.

If you pass -c <file>, Agency loads only that file and skips agency.local.json.

Don't put secrets in either file. Agency compiles config into the generated code, so these values can end up in build output. Keep secrets in .env.

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. With neither set, calls use gpt-5-mini through openai-responses. Naming a model without a provider lets the provider be inferred from the model.
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.
maxToolSchemaChars	Warns in the state log when one tool's JSON schema is longer than this. Default 2000; 0 disables it. A tool's schema is re-sent on every request, so an oversized one quietly raises the cost of the whole run.
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.
adaptersDir	The folder LoRA adapters (.safetensors files) are in. A local image server loads one the first time a call names it: generateImageLocal(..., lora: "sketch") loads sketch.safetensors from this folder. A relative path is taken from the folder agency.json is in.
controlnetsDir	The folder ControlNets are in, one directory each. agency local download controlnet-scribble-sdxl puts one here, and generateImageLocal(..., controlnet: "controlnet-scribble-sdxl", controlImage: "./pose.png") loads it. A relative path is taken from the folder agency.json is in.
llamaCpp.draftModel	A smaller GGUF model of the same family that drafts tokens for the main one, which is speculative decoding. agency run --local <model> --draft <model> sets it for a run.
llamaCpp.chatWrapper	The chat wrapper node-llama-cpp formats the model's prompts with, by its name (qwen, gemma4, harmony, chatML), for a model whose template it does not recognise.

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.