phi-agent 0.18.1

phi-agent — Rust AI Agent runtime framework: orchestration, sessions, streaming built-in. You define tools, prompts, domain knowledge.
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
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108

# API Reference

phi-agent's API documentation is auto-generated from doc comments and hosted on [docs.rs](https://docs.rs/phi-agent).

## Key Modules

| Module | Description |
|--------|-------------|
| `agent` | `PhiAgent`, `PhiAgentConfig`, `base_agent_builder()` factory |
| `config` | LLM configuration resolution (CLI > env > .env > default) |
| `prompt` | System prompt builders (`build_system_prompt`, `build_system_prompt_cn`) |
| `render` | `EventRenderer` trait + `TerminalRenderer`, `JsonStreamRenderer`, `NullRenderer` |
| `session` | Session management (ID, directory, file locking, cleanup) |
| `cli` | `AutoApprovalHandler`, `QueuedApprovalHandler` |
| `event_log` | Turn event → JSONL persistence |

## Builder Factories

| Function | Description |
|----------|-------------|
| `base_agent_builder()` | Default builder with compression middleware |
| `base_agent_builder_no_compression()` | Builder without compression (for custom context rotation) |
| `base_agent_builder_with_excludes()` | Builder that skips specific kernel tools |
| `base_agent_builder_with_options()` | Builder accepting custom `CompressionConfig` |

## Utility Functions

| Function | Description |
|----------|-------------|
| `format_number(n: u64)` | Compact number formatting for metrics displays: plain below 1K, then `1.2K`, `3.4M` |

## Re-exports from agent-base

phi-agent re-exports key types from [`agent-base`](https://docs.rs/agent-base):

| Category | Types |
|----------|-------|
| **Core** | `AgentResult`, `AgentError`, `AgentRuntime`, `Tool`, `ToolContext`, `Content`, `ToolMetadata`, `TypedTool` |
| **Approval** | `ApprovalHandler`, `ApprovalDecision`, `ApprovalRequest`, `AllowAllApprovalHandler`, `DenyAllApprovalHandler` |
| **Tool Policy** | `ToolPolicy`, `ToolDecision`, `DenyAllToolPolicy`, `ToolRegistry` |
| **Tool Visibility** | `ToolExposure`, `ActivationContext` |
| **LLM** | `ReasoningConfig`, `ReasoningEffort`, `llm_trait` (module: `LlmProvider`, `Protocol`, `config::LlmConfig`) |
| **Config** | `AgentConfig`, `SafetyConfig`, `SessionConfig`, `Language` |
| **Events** | `RuntimeEvent`, `UserEvent`, `FinishReason` |
| **Session** | `SessionId`, `TurnContext`, `ChatMessage` |
| **Plan** | `PlanItem`, `PlanStepStatus`, `UpdatePlanTool` |
| **Checkpoint** | `CheckpointData`, `CheckpointStep` |
| **Recovery** | `ConsecutiveFailureRecovery`, `RetryOnError` |
| **Context Window** | `ContextCompaction`, `ContextWindowManager`, `estimate_messages_tokens`, `first_system_prompt` |
| **Engine** | `MaxTurnsNudgeConfig`, `MaxTurnsNudgeMiddleware` |
| **Guard** | `GuardCtx`, `GuardDecision`, `Middleware`, `NoopGuard` |
| **Middleware** | `TurnFactMiddleware`, `TurnToolLimitMiddleware`, `PreLlmCtx`, `PostLlmCtx` |
| **Pipeline** | `DefaultPipeline`, `ToolExecutionPipeline` |

## Re-exports from agent-works

phi-agent re-exports key types from [`agent-works`](https://docs.rs/agent-works):

| Category | Types |
|----------|-------|
| **Builder** | `AgentBuilder` |
| **Focus** | `Focus`, `FocusContext`, `FocusInput`, `FocusOutput`, `FocusError` |
| **Prompt Fragments** | `PromptFragment`, `FragmentContext`, `compose_fragments`, `DynamicToolsFragment`, `EnvironmentFragment` |
| **Guard** | `DefaultGuard`, `DefaultGuardConfig`, `ReasoningOnlyAction` |
| **Token Budget** | `TokenBudgetAction`, `TokenBudgetConfig`, `TokenBudgetCore`, `TokenBudgetState`, `DEFAULT_SEED_MESSAGE`, `build_context_window_info`, `token_budget_base_overhead` |
| **Compression** | `CompressionMiddleware`, `clear_compression_cache`, `run_compact_session` (behind `compression`) |
| **MCP** | `McpServer`, `McpServerConfig`, `McpServeConfig` (behind `mcp`) |
| **Multi-Agent** | `MultiAgentConfig`, `ChildPermissionMode`, `ChildReport`, `ChildResultEvent`, `ControlConfig`, `ChildToolCapability`, `CapabilityResolution`, `resolve_capability` |
| **Fan-in** | `ChildResultRoute`, `ChildResultRouter` (behind `multi-agent`) |
| **Registry** | `AgentSnapshot`, `RegistrySnapshot` (behind `multi-agent`) |
| **Skills** | `Skill`, `PromptSkill` (behind `skill`) |

## Re-exports from llm-unified

| Function | Description |
|----------|-------------|
| `create_provider()` | LLM provider factory — resolves protocol/client from an `llm_trait` config |

## Feature-gated Re-exports

| Feature | Types |
|---------|-------|
| `shell` | `LocalShellTool` (from `phi-kernel-tools`) |
| `skill` | `Skill`, `PromptSkill` (from `agent-works`) |
| `mcp` | `McpServer`, MCP types (from `agent-works`) |
| `multi-agent` | `ChildResultRoute`, `ChildResultRouter`, `AgentSnapshot`, `RegistrySnapshot` |
| `compression` | `CompressionMiddleware`, `clear_compression_cache`, `run_compact_session` |
| `telemetry` | Metrics types (from `phi-telemetry`) |
| `browser` | 21 CDP browser automation tools (from `phi-tools`) |

## CLI Types

| Type | Description |
|------|-------------|
| `AutoApprovalHandler` | Auto / DenyAll approval mode |
| `QueuedApprovalHandler` | Enqueue approvals to a channel for UI consumption |
| `ApprovalItem` | Single queued approval request with oneshot response |
| `ApprovalMode` | CLI approval mode enum |

---

→ See the [Focus guide](guide/concepts/focus.md) for Focus usage examples.
→ See [Advanced Usage](guide/advanced/advanced.md) for ToolPolicy, compression, and PromptFragment examples.
→ See [Multi-Agent](guide/advanced/multi-agent.md) for fan-in routing and child permissions.

---

→ [Full API docs on docs.rs](https://docs.rs/phi-agent)