Crate phi_agent 

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

Built on agent-base and agent-works, providing builder factory, renderer, config resolution, session management, and other infrastructure. Ships with zero application tools. Kernel tools (file I/O, shell, multi-agent) are available via phi-kernel-tools behind feature flags — all off by default. Application tools are injected by consumers.

Re-exports

pub use agent::PhiAgent;

pub use agent::PhiAgentConfig;

pub use agent::base_agent_builder;

pub use agent::base_agent_builder_with_excludes;

pub use agent::base_agent_builder_with_options;

pub use agent::clear_compression_cache;

pub use agent::run_compact_session;

pub use cli::ApprovalMode;

pub use cli::AutoApprovalHandler;

pub use config::LlmConfig;

pub use config::resolve_llm_config;

pub use event_log::event_to_jsonl;

pub use event_log::event_to_value;

pub use event_log::save_turn_log;

pub use prompt::build_system_prompt;

pub use prompt::build_system_prompt_cn;

pub use render::EventRenderer;

pub use render::JsonStreamRenderer;

pub use render::NullRenderer;

pub use render::OutputFormat;

pub use render::create_renderer;

pub use render::create_stdout_renderer;

pub use session::SessionContext;

pub use session::SnapshotInfo;

pub use session::cleanup_expired_sessions;

pub use session::create_snapshot;

pub use session::delete_snapshot;

pub use session::list_snapshots;

pub use session::resolve_session;

pub use session::restore_snapshot;

pub use session::validate_session_id;

pub use session::validate_snapshot_name;

Modules

agent

Agent construction and lifecycle management.

bridge

Bridge protocol — adapts phi-agent for SDK consumption.

cli

CLI helpers — approval strategies and utilities shared across consumers.

config

Configuration resolution helpers.

event_log

Event log: serialize turn events to JSONL files.

prompt

System prompt generation (EN/CN).

render

Event renderers — transform RuntimeEvent streams into display output.

session

Session management — ID resolution, locking, snapshots, cleanup.

Structs

AgentBuilder

AgentRuntime

ApprovalRequest

CompressionMiddleware

Middleware that compresses conversation history before each LLM call.

ConsecutiveFailureRecovery

Recovery strategy that tracks consecutive failures per tool and stops after a limit.

Focus

A focused LLM call.

FocusContext

Structured context for multi-field input scenarios.

FocusOutput

Output wrapper for a Focus call.

McpServeConfig

Configuration for running as an MCP server.

McpServer

An MCP Server that wraps an AgentRuntime and exposes it as an MCP tool.

McpServerConfig

OpenAiClient

PlanItem

A single step in a lightweight plan checklist.

PostLlmCtx

PreLlmCtx

ReasoningConfig

Reasoning/thinking configuration, unifying reasoning/thinking parameters across vendors.

SafetyConfig

Safety configuration for agent runtime guardrails.

SessionId

SessionMetrics

Accumulated session metrics. Written incrementally to session_metrics.json at the end of each turn.

SessionSummary

Lightweight summary returned by list_all().

ToolContext

ToolMetadata

Machine-readable metadata for a registered tool — origin, version, and runtime requirements in a stable shape consumers can inspect without parsing the LLM-facing definition JSON.

TurnFactMiddleware

Turn fact summary middleware — injects structured facts from the previous turn’s tool results into the next user message.

TurnMetrics

Per-turn metrics — one per LLM interaction.

TurnToolLimitMiddleware

Middleware that enforces a hard limit on tool calls per turn.

UpdatePlanTool

A lightweight tool that records and displays a plan checklist to the user.

UserMessageCtx

Enums

AgentError

ApprovalDecision

Content

Structured content returned by a tool, aligned with the MCP content array shape (no envelope, no orchestration/failure/truncation semantics).

FinishReason

Semantic finish reason, replacing scattered Option<String> matching.

FocusError

Error type for Focus calls.

McpServerTransport

Transport mode for the MCP server.

McpTransport

PlanStepStatus

Lightweight plan step status — display-only, no execution semantics.

ReasoningEffort

Reasoning intensity/depth enumeration.

RiskLevel

RunOutcome

The outcome of an Agent turn or run.

RuntimeEvent

Unified runtime event — the single event type for both internal and external consumers (frontends, CLIs, tests).

SessionOutcome

Outcome of a session (the entire conversation).

TurnOutcome

Outcome of a single turn (one LLM interaction).

Traits

ApprovalHandler

Trait for handling tool approval requests.

FocusInput

Input for a Focus call — either a simple string or a structured context.

LlmClient

Middleware

Tool

ToolPolicy

Policy-based control over tool execution.

Functions

list_all_metrics

List all session summaries by scanning the sessions directory. Reads each session_metrics.json and extracts summary fields.

load_metrics

Load session metrics from session_metrics.json in a session directory.

save_metrics

Incrementally write session metrics to session_metrics.json. Overwrites the file on each call — safe for per-turn writes.

try_load_metrics

Try to load session metrics, returning None if the file doesn’t exist.

Type Aliases

AgentResult