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
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216

# phi-agent — Rust AI Agent Framework

<picture><source media="(prefers-color-scheme: dark)" srcset="assets/logo.svg"><img alt="phi-agent" src="assets/logo.svg" height="60"></picture>

[![CI](https://github.com/hibuka-labs/phi-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/hibuka-labs/phi-agent/actions)
[![Crates.io](https://img.shields.io/crates/v/phi-agent.svg)](https://crates.io/crates/phi-agent)
[![Docs.rs](https://docs.rs/phi-agent/badge.svg)](https://docs.rs/phi-agent)
[![codecov](https://codecov.io/gh/hibuka-labs/phi-agent/branch/main/graph/badge.svg)](https://codecov.io/gh/hibuka-labs/phi-agent)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Documentation](https://img.shields.io/badge/docs-book-green.svg)](https://docs.phiagent.dev)
[![PyPI](https://img.shields.io/pypi/v/phi-agent.svg)](https://pypi.org/project/phi-agent/)

Rust AI Agent runtime framework — orchestration, sessions, streaming all built-in. You only define tools, prompts, and domain knowledge.

> **phi-agent ships with zero application tools.** No web search, no database connector, no code executor — just a clean Rust runtime. What tools your agent needs is entirely up to you. Kernel primitives (file I/O, shell, sub-agents) are available via `phi-kernel-tools` as opt-in infrastructure behind feature flags. File tools and MCP are on by default; shell and multi-agent are opt-in.

Built on [agent-base](https://crates.io/crates/agent-base) and [agent-works](https://crates.io/crates/agent-works). **phi-agent provides the infrastructure. You bring the tools.**

## Ecosystem

| Crate | crates.io | Description |
|-------|-----------|-------------|
| `agent-base` | [![Crates.io](https://img.shields.io/crates/v/agent-base.svg)](https://crates.io/crates/agent-base) | Lightweight runtime kernel — LLM clients, Tool trait, event stream |
| `agent-works` | [![Crates.io](https://img.shields.io/crates/v/agent-works.svg)](https://crates.io/crates/agent-works) | Batteries-included toolbox — MCP, Skills, Focus |
| `phi-agent` | [![Crates.io](https://img.shields.io/crates/v/phi-agent.svg)](https://crates.io/crates/phi-agent) | Full framework — Builder factory, renderers, config, CLI binary |

**Just need the runtime?** `cargo add agent-base`. **Want the full framework?** `cargo add phi-agent`.

## Architecture

```mermaid
graph TB
    AB[agent-base<br/>Tool trait · Runtime<br/>LLM clients · Events]

    AB --> AW[agent-works<br/>MCP · Skills · Focus]
    AB --> PKT["phi-kernel-tools<br/>Kernel tools"]
    AB --> YT[your-tools<br/>Custom Tool impls]

    AW --> PA
    PKT --> PA
    YT --> PA

    PA[phi-agent<br/>Builder factory<br/>Renderers · Config · Session<br/>CLI binary]
```

### Kernel Tools & Protocols

All opt-in via feature flags. `file` and `mcp` are enabled by default; `shell` and `multi-agent` are off.

| Feature | Capability | Default |
|---------|------------|---------|
| `file` | Read, write, list files + skills | **On** |
| `mcp` | Model Context Protocol support | **On** |
| `shell` | Execute shell commands | Off |
| `multi-agent` | Spawn sub-agents | Off |
| `browser` | Browser automation via CDP | Off |

**Feature groups** (convenience bundles):

| Group | Includes | In `full`? |
|-------|----------|------------|
| `protocol` | `mcp` | Yes |
| `observability` | `telemetry` + `logging` | Yes |
| `app` | `browser` | **No** |
| `full` | `file` + `shell` + `mcp` + `telemetry` + `logging` | — |

`telemetry` and `logging` are in the default set. `app` (browser) is intentionally excluded from `full` — add it explicitly when needed. `multi-agent` is always opt-in, not included in any group.

## Why phi-agent

**Your domain, your rules.** Agent loop, session management, streaming events, tool routing, approval hooks — the framework does it all. You write zero glue code and focus on domain logic.

**Single binary.** Compile to one file, drop it in, run it. `cargo install phi-agent` — that's it.

**Every step auditable.** Every LLM call, every tool execution, recorded as JSONL. Sessions are snapshot-able, behavior is traceable, issues are debuggable.

## Quick Start

```rust
use phi_agent::{
    base_agent_builder, build_system_prompt, PhiAgent, PhiAgentConfig,
    OpenAiClient, SafetyConfig, ReasoningEffort,
};
use std::sync::Arc;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let llm_client = Arc::new(OpenAiClient::new(
        std::env::var("LLM_API_KEY")?,
        "gpt-4o".into(),
        Some("https://api.openai.com/v1".into()),
    ));

    let builder = base_agent_builder(llm_client)
        .system_prompt(build_system_prompt())
        .register_tool(your_tool);

    let agent = PhiAgent::build(builder, PhiAgentConfig {
        model: "gpt-4o".into(),
        enable_thinking: true,
        thinking_budget: None,
        thinking_effort: ReasoningEffort::Medium,
        safety: SafetyConfig::default(),
    })?;

    let session = agent.create_session().await;
    let renderer = phi_agent::create_stdout_renderer(
        &phi_agent::OutputFormat::Terminal {
            show_thinking: true,
            show_tool_args: true,
            color: true,
        }
    );

    agent.run_turn(session, "Hello!", |event| {
        renderer.render(event)
    }).await?;

    Ok(())
}
```

More examples in [examples/](examples/).

## CLI

```bash
# Basic install (file + MCP + telemetry + logging)
cargo install phi-agent

# With shell execution (most common)
cargo install phi-agent --features shell

# Everything except browser
cargo install phi-agent --features full

# Everything including browser
cargo install phi-agent --features full,app

phi "What's in this directory?"
```

**Development (from source):**

```bash
git clone https://github.com/hibuka-labs/phi-agent.git && cd phi-agent

cargo run                              # default: file + MCP + telemetry + logging
cargo run --features shell             # + shell execution
cargo run --features full              # everything except browser
cargo run --features full,app          # everything including browser
```

```bash
# REPL mode
phi

# JSON output
phi --format json "List files"
```

## Documentation

📖 **[docs.phiagent.dev](https://docs.phiagent.dev)**

| | |
|---|---|
| [Getting Started](https://docs.phiagent.dev/guide/getting-started/) | [Custom Tools](https://docs.phiagent.dev/guide/tools/custom-tool/) |
| [Kernel Tools](https://docs.phiagent.dev/guide/tools/file-tools/) | [MCP](https://docs.phiagent.dev/guide/advanced/mcp/) |
| [Multi-Agent](https://docs.phiagent.dev/guide/advanced/multi-agent/) | [Skills](https://docs.phiagent.dev/guide/concepts/skills/) |
| [Session & Snapshots](https://docs.phiagent.dev/guide/advanced/session/) | [Observability](https://docs.phiagent.dev/guide/advanced/observability/) |
| [Configuration](https://docs.phiagent.dev/guide/getting-started/configuration/) | [API Reference](https://docs.rs/phi-agent) |

## Contributing

```bash
git clone git@github.com:hibuka-labs/phi-agent.git
cd phi-agent
cargo check
```

See [CONTRIBUTING.md](CONTRIBUTING.md).

## Contributors ✨

Thanks goes to these wonderful people:

<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->
<table>
  <tbody>
    <tr>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/aislopking024"><img src="https://avatars.githubusercontent.com/u/106123738?v=4" width="100px;" alt="aislopking024"/><br /><sub><b>shard</b></sub></a><br /><a href="https://github.com/hibuka-labs/phi-agent/commits?author=aislopking024" title="Code">💻</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/Krshs90"><img src="https://avatars.githubusercontent.com/u/201503093?v=4" width="100px;" alt="Krshs90"/><br /><sub><b>Krish Shah</b></sub></a><br /><a href="https://github.com/hibuka-labs/phi-agent/commits?author=Krshs90" title="Code">💻</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/slegarraga"><img src="https://avatars.githubusercontent.com/u/64795732?v=4" width="100px;" alt="slegarraga"/><br /><sub><b>Sebastian Legarraga</b></sub></a><br /><a href="https://github.com/hibuka-labs/phi-agent/commits?author=slegarraga" title="Code">💻</a> <a href="https://github.com/hibuka-labs/phi-agent/commits?author=slegarraga" title="Tests">⚠️</a> <a href="https://github.com/hibuka-labs/phi-agent/commits?author=slegarraga" title="Examples">💡</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/MsfPablo"><img src="https://avatars.githubusercontent.com/u/129399053?v=4" width="100px;" alt="MsfPablo"/><br /><sub><b>Pablo Garcia</b></sub></a><br /><a href="https://github.com/hibuka-labs/phi-agent/commits?author=MsfPablo" title="Code">💻</a> <a href="https://github.com/hibuka-labs/phi-agent/commits?author=MsfPablo" title="Tests">⚠️</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/LetMeSleep8h"><img src="https://avatars.githubusercontent.com/u/183817470?v=4" width="100px;" alt="LetMeSleep8h"/><br /><sub><b>Sleep8h</b></sub></a><br /><a href="https://github.com/hibuka-labs/phi-agent/commits?author=LetMeSleep8h" title="Code">💻</a> <a href="https://github.com/hibuka-labs/phi-agent/commits?author=LetMeSleep8h" title="Tests">⚠️</a></td>
    </tr>
  </tbody>
</table>
<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
<!-- ALL-CONTRIBUTORS-LIST:END -->

([emoji key](https://allcontributors.org/docs/en/emoji-key)) — This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification.

## License

MIT — see [LICENSE](LICENSE).

## Contact

[phiagent@hibuka.com](mailto:phiagent@hibuka.com)

[中文](README_CN.md)