Pi Agent: Configuration Deep Dive
Last updated: 2026-08-31
Configuration is Pi Agent's "control panel" — understand it to fine-tune every parameter.
1. Configuration Layers
Pi Agent config priority from low to high:
TEXT
📖 Display only
Defaults → Global Config → Project Config → Env Vars → Code Params → CLI Params
(lowest) (highest)
Higher priority overrides lower.
2. Global Configuration
Location: ~/.pi-agent/config.yaml
YAML
default_provider: deepseek
default_model: deepseek-chat
providers:
deepseek:
api_key: "sk-xxxxxxxx"
base_url: "https://api.deepseek.com"
model: "deepseek-chat"
temperature: 0.7
max_tokens: 4096
openai:
api_key: "sk-xxxxxxxx"
model: "gpt-4o"
display:
theme: dark
code_highlight: true
show_token_count: true
session:
auto_save: true
save_dir: "~/.pi-agent/sessions"
templates_dir: "~/.pi-agent/templates"
skills_dir: "~/.pi-agent/skills"
3. Project Configuration
Location: .pi-agent.yaml in project root
YAML
project:
name: "my_fastapi_app"
description: "FastAPI project"
agent:
system_prompt: "You are the dedicated assistant for this FastAPI project"
tools:
- file_reader
- shell
- search
context:
inject:
- "README.md"
- "requirements.txt"
providers:
deepseek:
temperature: 0.3
4. Environment Variables
All config items have corresponding env vars with PI_ prefix:
| Config Item | Environment Variable |
|---|---|
| providers.deepseek.api_key | PI_DEEPSEEK_API_KEY |
| default_provider | PI_DEFAULT_PROVIDER |
| display.theme | PI_DISPLAY_THEME |
| session.auto_save | PI_SESSION_AUTO_SAVE |
| agent.temperature | PI_AGENT_TEMPERATURE |
5. Code Configuration
PYTHON
from pi_agent import Agent
agent = Agent(
name="custom",
provider="deepseek",
model="deepseek-chat",
temperature=0.5,
max_tokens=2048,
tools=["search", "calculator"],
system_prompt="You are a math assistant",
context_window=8192,
truncation_strategy="summarize",
auto_save=True
)
6. Dynamic Configuration
Modify config at runtime:
PYTHON
agent.configure(model="deepseek-reasoner", temperature=0.2)
agent.enable_tool("shell")
agent.disable_tool("search")
agent.set_system_prompt("You are now a strict security reviewer")
7. Configuration Reference
| Category | Item | Default | Description |
|---|---|---|---|
| Agent | name | "agent" | Agent name |
| Agent | system_prompt | "" | System prompt |
| Agent | temperature | 0.7 | Temperature |
| Agent | max_tokens | 4096 | Max output tokens |
| Agent | context_window | 8192 | Context window |
| Agent | truncation_strategy | "remove_oldest" | Truncation strategy |
| Provider | api_key | "" | API key |
| Provider | base_url | "" | API base URL |
| Provider | model | "" | Model name |
| Display | theme | "dark" | UI theme |
| Session | auto_save | false | Auto-save sessions |
FAQ
Q What must be configured?
A Only the API key (
providers.<name>.api_key). Everything else has defaults. Local models don't even need a key.Q Project vs global config conflicts?
A Project config wins — "proximity principle": project > user > global defaults.
Q Can I commit config to Git?
A Project config (.pi-agent.yaml) yes, but don't include API keys. Use env vars for secrets.
Summary
- Priority: defaults < global < project < env vars < code < CLI
- Global:
~/.pi-agent/config.yaml; Project:.pi-agent.yaml - Env vars:
PI_+ uppercase key name - Runtime dynamic configuration supported
- API keys via env vars, never commit to Git
Exercises
- Basic (Difficulty: ⭐): Create a global config file with at least one LLM provider.
- Intermediate (Difficulty: ⭐⭐): Create
.pi-agent.yamlfor your project with custom system prompt and tools. - Advanced (Difficulty: ⭐⭐⭐): Write a config validation script that checks completeness and consistency.
