phi-agent — Rust AI Agent Framework

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 and agent-works. phi-agent provides the infrastructure. You bring the tools.

Ecosystem

Crate	crates.io	Description
agent-base		Lightweight runtime kernel — LLM clients, Tool trait, event stream
agent-works		Batteries-included toolbox — MCP, Skills, Focus
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

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 groups (convenience bundles):

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

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/.

CLI

# 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):

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

# REPL mode
phi

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

Documentation

📖 docs.phiagent.dev

Contributing

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

See CONTRIBUTING.md.

Contributors ✨

Thanks goes to these wonderful people:

(emoji key) — This project follows the all-contributors specification.

License

MIT — see LICENSE.

Contact

phiagent@hibuka.com

中文