Configuration

Configure your agents using environment variables or a settings.json file. Environment variables take priority, making it easy to override settings per-environment.

---

Quick Start

Set your model and tools with environment variables:

export GEMINI_API_KEY="your-api-key"
export AGENT_DEFAULT_MODEL="gemini-3-flash-preview"
export AGENT_DEFAULT_TOOLS="read,write,bash"

Or create a settings.json in your project root:

{
  "defaultModel": "gemini-3-flash-preview",
  "maxIterations": 100,
  "defaultTools": ["read", "write", "bash", "grep"]
}

---

Environment Variables

Variable	Type	Default	Description
GEMINI_API_KEY	string	—	Required. Your Gemini API key
AGENT_DEFAULT_MODEL	string	gemini-3-flash-preview	Model to use for agent interactions
AGENT_MAX_ITERATIONS	number	100	Maximum loop iterations (prevents runaway agents)
AGENT_DEFAULT_TOOLS	string	All tools	Comma-separated list of tool names
AGENT_SETTINGS_PATH	string	./settings.json	Path to settings file
AGENT_ARTIFACTS_PATH	string	.agent	Base path for project-level artifacts (skills, subagents)
AGENT_GLOBAL_ARTIFACTS_PATH	string	~/.agent	Path for user-level global artifacts
AGENT_STREAM_SUBAGENTS	boolean	false	Stream subagent output to the main agent (true/false)
AGENT_DISABLED_SKILLS	string	—	Comma-separated skill names to disable
AGENT_DISABLED_SUBAGENTS	string	—	Comma-separated subagent names to disable

Environment variables override settings.json values. This lets you use a base config file while customizing per-environment.

---

Settings File

Create settings.json in your project root or specify a custom path with AGENT_SETTINGS_PATH.

Full Example

{
  "defaultModel": "gemini-3-flash-preview",
  "maxIterations": 100,
  "defaultTools": [
    "sleep",
    "plan",
    "read",
    "write",
    "grep",
    "bash",
    "web_fetch",
    "web_search"
  ],
  "artifactsPath": ".agent",
  "streamSubagents": false,
  "disabledSkills": [],
  "disabledSubagents": []
}

Schema

Field	Type	Default	Description
defaultModel	string	gemini-3-flash-preview	Model identifier for API calls
maxIterations	number	100	Maximum agent loop iterations
defaultTools	string[]	All tools	Tools to load when none specified
artifactsPath	string	.agent	Base path for project-level artifacts (skills, subagents)
streamSubagents	boolean	false	Stream subagent output to the main agent
disabledSkills	string[]	[]	Skill names to exclude from loading
disabledSubagents	string[]	[]	Subagent names to exclude from loading

---

Priority Order

Configuration values are resolved in this order (first wins):

1. Environment variables: AGENT_* prefixed vars
2. settings.json: Values from the JSON file
3. Defaults: Built-in default values

# Environment variable wins over settings.json
export AGENT_DEFAULT_MODEL="gemini-3-pro"  # Uses this, not settings.json

---

Next Steps

Agent Loop How the core loop works

Built-in Tools Available tools reference