Pi Agent: Configuration Deep Dive
最終更新:2026-08-31
--- title: "設定詳解" description: "Pi Agentの設定体系を包括的に理解し、設定ファイル構造、レイヤーオーバーライド、環境変数を学びます。" order: 12 lang: ja
設定はPi Agentの「コントロールパネル」——理解すれば、すべてのパラメータを微調整できる。
1. 設定レイヤー
Pi Agentの設定優先度は低い順:
TEXT
📖 参照専用
デフォルト → グローバル設定 → プロジェクト設定 → 環境変数 → コード引数 → CLI引数
(最低) (最高)
優先度が高いものが低いものを上書きします。
2. グローバル設定
場所:~/.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. プロジェクト設定
場所:プロジェクトルートの .pi-agent.yaml
YAML
project:
name: "my_fastapi_app"
description: "FastAPIプロジェクト"
agent:
system_prompt: "あなたはこのFastAPIプロジェクトの専用アシスタントです"
tools:
- file_reader
- shell
- search
context:
inject:
- "README.md"
- "requirements.txt"
providers:
deepseek:
temperature: 0.3
4. 環境変数
すべての設定項目には PI_ プレフィックスの環境変数が対応します:
| 設定項目 | 環境変数 |
|---|---|
| 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. コード設定
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="あなたは数学アシスタントです",
context_window=8192,
truncation_strategy="summarize",
auto_save=True
)
6. 動的設定
実行時に設定を変更:
PYTHON
agent.configure(model="deepseek-reasoner", temperature=0.2)
agent.enable_tool("shell")
agent.disable_tool("search")
agent.set_system_prompt("あなたは厳格なセキュリティレビューアーです")
7. 設定リファレンス
| カテゴリ | 項目 | デフォルト | 説明 |
|---|---|---|---|
| Agent | name | "agent" | Agent名 |
| Agent | system_prompt | "" | システムプロンプト |
| Agent | temperature | 0.7 | Temperature |
| Agent | max_tokens | 4096 | 最大出力トークン |
| Agent | context_window | 8192 | コンテキストウィンドウ |
| Agent | truncation_strategy | "remove_oldest" | 切り詰め戦略 |
| Provider | api_key | "" | APIキー |
| Provider | base_url | "" | APIベースURL |
| Provider | model | "" | モデル名 |
| Display | theme | "dark" | UIテーマ |
| Session | auto_save | false | セッション自動保存 |
❓ よくある質問
Q 何を設定しなければなりませんか?
A APIキー(
providers.<name>.api_key)だけです。他はすべてデフォルト値があります。ローカルモデルならキーすら不要です。Q プロジェクト設定とグローバル設定が競合したら?
A プロジェクト設定が優先されます——「近接性の原則」:プロジェクト>ユーザー>グローバルデフォルト。
Q 設定をGitにコミットしてもよい?
A プロジェクト設定(.pi-agent.yaml)はOKですが、APIキーは含めないでください。シークレットは環境変数で。
📖 まとめ
- 優先度:デフォルト<グローバル<プロジェクト<環境変数<コード<CLI
- グローバル:
~/.pi-agent/config.yaml;プロジェクト:.pi-agent.yaml - 環境変数:
PI_+キー名の大文字 - 実行時の動的設定をサポート
- APIキーは環境変数で、Gitには絶対コミットしない
📝 練習問題
- 基礎(難易度:⭐): 少なくとも1つのLLMプロバイダーを含むグローバル設定ファイルを作成してください。
- 中級(難易度:⭐⭐): プロジェクトに
.pi-agent.yamlを作成し、カスタムシステムプロンプトとツールを設定してください。 - 上級(難易度:⭐⭐⭐): 設定の完全性と一貫性をチェックする設定検証スクリプトを書いてください。