phi-agent 0.2.6

phi-agent — General-purpose AI Agent framework (builder factory, renderer, config, session management)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88

# Configuration

All configuration options and how to set them.

## LLM Configuration

Environment variables (`.env` file or system env):

| Variable | Description | Default |
|----------|-------------|---------|
| `LLM_API_KEY` | API key (required) | — |
| `LLM_MODEL` | Model name | `gpt-4o` |
| `LLM_BASE_URL` | API endpoint | `https://api.openai.com/v1` |

Also accepts `OPENAI_API_KEY`, `OPENAI_MODEL`, `OPENAI_BASE_URL` as fallbacks.

### Priority

```
CLI argument > environment variable > .env file > default
```

## Agent Configuration

`PhiAgentConfig` fields:

| Field | Type | Description | Default |
|-------|------|-------------|---------|
| `model` | `String` | Model name passed to provider | — |
| `enable_thinking` | `bool` | Enable chain-of-thought | `true` |
| `thinking_budget` | `Option<u64>` | Token budget for thinking | `None` (provider default) |
| `thinking_effort` | `ReasoningEffort` | Low / Medium / High / XHigh | `Medium` |
| `safety` | `SafetyConfig` | Tool call limits | See below |

## Safety Config

```rust
SafetyConfig {
    max_tool_calls_per_turn: 30,   // Max tool invocations per turn
    max_consecutive_failures: 3,   // Stop after N consecutive failures
}
```

## CLI Flags

| Flag | Description |
|------|-------------|
| `--format <fmt>` | Output format: `terminal`, `json`, `quiet` |
| `--model <name>` | Override model name |
| `--base-url <url>` | Override API base URL |
| `--no-thinking` | Disable thinking/chain-of-thought |
| `--thinking-budget <n>` | Token budget for thinking |
| `--thinking-effort <level>` | `low` / `medium` / `high` / `xhigh` |
| `--no-tool-args` | Hide tool argument details |
| `--no-color` | Disable terminal colors |
| `--max-tool-calls <n>` | Max tool calls per turn |
| `--max-failures <n>` | Max consecutive failures |
| `-y` / `--auto-approve` | Auto-approve all tool calls |
| `--session-id <id>` | Specify session ID |
| `--shell-timeout-ms <ms>` | Timeout for shell commands |
| `--log-dir <dir>` | Log directory (default `~/.phi-agent`) |
| `--log-level <level>` | Log level (default `info`) |
| `--no-log` | Disable file logging |

## Output Formats

| Format | CLI Flag | Use Case |
|--------|----------|----------|
| Terminal | `--format terminal` (default) | Human interaction — colors, emoji, streaming |
| JSON | `--format json` | Scripting / IDE integration — one JSON per line |
| Quiet | `--format quiet` | Web backend — no stdout, tracing only |

## Session Directory

Sessions stored at `~/.phi-agent/sessions/<session_id>/`:

```
session_id            # Session ID marker
session.lock          # File lock (prevent concurrent access)
session_meta.json     # Creation time, last active time
session_metrics.json  # Metrics (tokens, latency, cost)
session.log           # Human-readable log (if enabled)
turn_001.jsonl        # Per-turn event log
turn_002.jsonl
...
```

Sessions inactive for 7+ days are auto-cleaned at startup.