Rust AI Agent framework. Agent orchestration, session management, streaming output — the framework handles it. You write three things: your tools, your prompts, your 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, zero runtime deps. No Node.js. No Python. Compile to one file, drop it in, run it. cargo install, ten seconds.

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.

License

MIT — see LICENSE.

Contact

phiagent@hibuka.com

中文