Pi Agent: Troubleshooting & AI Providers
Last updated: 2026-08-31
Don't panic when things break — 90% of issues can be resolved on this page.
1. Common Troubleshooting
(1) Installation Issues
| Problem | Cause | Solution |
|---|---|---|
| pip install fails | Old pip version | pip install --upgrade pip |
| Network timeout | Network issues | Use mirror: -i https://pypi.tuna.tsinghua.edu.cn/simple |
| Compile error | Missing build tools | Install build-essential (Linux) or VS Build Tools (Windows) |
| Permission error | Global install needs root | Use --user or virtualenv |
(2) API Call Issues
| Error Code | Meaning | Solution |
|---|---|---|
| 401 | Auth failed | Check API key |
| 429 | Rate limited | Reduce request frequency or upgrade plan |
| 500 | Server error | Retry later |
| 503 | Service unavailable | Check provider status page |
(3) Tool Call Issues
| Problem | Cause | Solution |
|---|---|---|
| Tool unresponsive | Insufficient permissions | Check trust level and tool permissions |
| Tool timeout | Execution too long | Increase max_execution_time |
| Empty result | Bad input params | Check parameter types and format |
| File not found | Wrong path | Use absolute paths |
2. Debugging Tips
(1) Enable Debug Mode
BASH
pi-agent chat --debug
PYTHON
agent = Agent(name="debug", debug=True)
(2) Detailed Logging
PYTHON
import logging
logging.basicConfig(level=logging.DEBUG)
agent = Agent(name="debug")
agent.chat("Test message")
(3) Event Tracing
PYTHON
@agent.on("*")
def trace(event):
print(f"[{event.timestamp}] {event.name}: {event.data}")
3. AI Provider Reference
(1) DeepSeek
YAML
providers:
deepseek:
api_key: "sk-xxxxxxxx"
base_url: "https://api.deepseek.com"
models:
- name: deepseek-chat
context: 64000
input_price: 1.0
output_price: 2.0
- name: deepseek-reasoner
context: 64000
input_price: 4.0
output_price: 16.0
(2) OpenAI
YAML
providers:
openai:
api_key: "sk-xxxxxxxx"
base_url: "https://api.openai.com/v1"
models:
- name: gpt-4o
context: 128000
input_price: 2.5
output_price: 10.0
- name: gpt-4o-mini
context: 128000
input_price: 0.15
output_price: 0.6
(3) Anthropic
YAML
providers:
anthropic:
api_key: "sk-ant-xxxxxxxx"
base_url: "https://api.anthropic.com"
models:
- name: claude-sonnet-4-20250514
context: 200000
input_price: 3.0
output_price: 15.0
- name: claude-3-5-haiku-20241022
context: 200000
input_price: 0.8
output_price: 4.0
(4) Google Gemini
YAML
providers:
gemini:
api_key: "AIzaxxxxxxxx"
base_url: "https://generativelanguage.googleapis.com/v1beta"
models:
- name: gemini-2.0-flash
context: 1048576
input_price: 0.1
output_price: 0.4
(5) llama.cpp
YAML
providers:
local:
type: llama_cpp
model_path: "./models/qwen2.5-7b-instruct-q4_k_m.gguf"
n_gpu_layers: -1
n_ctx: 4096
(6) Ollama
YAML
providers:
ollama:
type: ollama
base_url: "http://localhost:11434"
model: "qwen2.5:7b"
4. Performance Optimization
PYTHON
agent = Agent(
max_tokens=2048,
temperature=0.3,
context_window=4096,
provider="deepseek",
auto_summarize=True
)
5. Health Check
Example 1: Diagnostic Script (Difficulty: ⭐)
PYTHON
from pi_agent import Config, Agent
print("=== Pi Agent Diagnostics ===")
config = Config.load()
print(f"Config: {'OK' if config else 'Not found'}")
for name, provider in config.providers.items():
try:
agent = Agent(provider=name)
agent.chat("ping")
print(f"Provider {name}: OK")
except Exception as e:
print(f"Provider {name}: FAIL ({e})")
print("=== Diagnostics Complete ===")
FAQ
Q Agent never responds?
A Check network, API key validity, provider service status. Enable debug mode for detailed request logs.
Q Tool call permission denied?
A Check project trust level. shell and file_write need trusted or restricted level.
Q Switch to cheaper model?
A Interactive:
/model gpt-4o-mini. Code: Agent(model="deepseek-chat"). Config: change default_model.Summary
- Three issue categories: installation, API, tools — each with troubleshooting paths
- Debug toolkit: --debug, logging, event tracing
- 6 AI providers with complete configuration reference
- Performance optimization: reduce latency, reduce cost, control concurrency
- Health check script for quick problem diagnosis
Exercises
- Basic (Difficulty: ⭐): Run the health check script, confirm your environment is properly configured.
- Intermediate (Difficulty: ⭐⭐): Configure two providers, write code to auto-failover to backup provider.
- Advanced (Difficulty: ⭐⭐⭐): Implement a complete monitoring solution: periodic provider checks, response latency tracking, token usage trends, alerting on anomalies.
