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_no_compression;

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::ApprovalItem;

pub use cli::ApprovalMode;

pub use cli::AutoApprovalHandler;

pub use cli::QueuedApprovalHandler;

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 prompt::build_system_prompt_with_fragments;

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::SessionInfo;

pub use session::SnapshotInfo;

pub use session::cleanup_expired_sessions;

pub use session::clear_messages_jsonl;

pub use session::create_snapshot;

pub use session::delete_snapshot;

pub use session::list_sessions;

pub use session::list_snapshots;

pub use session::load_session_messages;

pub use session::persist_window_messages;

pub use session::read_session_title;

pub use session::resolve_session;

pub use session::restore_snapshot;

pub use session::validate_session_id;

pub use session::validate_snapshot_name;

pub use session::write_session_title;

pub use agent_base::llm_trait;

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). System prompt construction using composable fragments.

render

Event renderers — transform RuntimeEvent streams into display output.

session

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

Structs

AgentBuilder

AgentRuntime

AllowAllApprovalHandler

ApprovalRequest

CheckpointData

CompactionOutcome

Successful compaction outcome: what happened plus the messages to install.

CompressionMiddleware

Middleware that compresses conversation history before each LLM call.

ConsecutiveFailureRecovery

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

ContextWindowManager

DefaultGuard

Guard policies from agent-works (tool gating, reasoning-only enforcement). Default guard implementation

DefaultGuardConfig

Guard policies from agent-works (tool gating, reasoning-only enforcement). Default guard configuration

DenyAllApprovalHandler

DynamicToolsFragment

Dynamically generate tool descriptions from registered tools.

EnvironmentFragment

Injects runtime environment information: OS, working directory, git branch.

Focus

A focused LLM call.

FocusContext

Structured context for multi-field input scenarios.

FocusOutput

Output wrapper for a Focus call.

FragmentContext

Context passed to each fragment during rendering.

MaxTurnsNudgeConfig

Middleware that nudges the model when it nears the turn limit. Configuration for the max-turns nudge middleware.

MaxTurnsNudgeMiddleware

Middleware that nudges the model when it nears the turn limit. Middleware that injects a nudge message when approaching the max turns limit.

McpServeConfig

Configuration for running as an MCP server.

McpServer

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

McpServerConfig

PlanItem

A single step in a lightweight plan checklist.

PostLlmCtx

PreLlmCtx

ReasoningConfig

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

RepeatToolLimitConfig

Middleware that breaks repeated identical tool-call loops (e.g. polling). Configuration for RepeatToolLimitMiddleware.

RepeatToolLimitMiddleware

Middleware that breaks repeated identical tool-call loops (e.g. polling). Break poll loops — repeated identical tool calls — hard.

RetryOnError

Continue on tool failure, feeding the error back to the model

SafetyConfig

Safety configuration for agent runtime guardrails.

SessionId

Unique identifier for an agent session.

SessionMetrics

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

SessionSummary

Lightweight summary returned by list_all().

TokenBudgetConfig

Configuration for the token-budget window strategy.

TokenBudgetCore

Pure decision core for the token-budget window strategy.

TokenBudgetState

State tracker for the token budget across compaction calls within a single window.

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.

ToolRegistry

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

ChatMessage

A chat message in a conversation.

CheckpointStep

CompactionKind

What a successful ContextCompaction::compact actually did to the history. agent-base stays strategy-free: it only relays the kind into the log line, so a nudge append never reads as a compaction and a real replacement always does (issue #33).

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.

Language

McpServerTransport

Transport mode for the MCP server.

McpTransport

NoticeKind

Notice kinds for UserEvent::Notice — consumers match on these to decide rendering (e.g. Warning → persistent red line). Notice category — decides how consumers render the notification.

PlanStepStatus

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

ReasoningEffort

Reasoning intensity/depth enumeration.

ReasoningOnlyAction

Guard policies from agent-works (tool gating, reasoning-only enforcement). Reasoning-only handling strategy

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

TokenBudgetAction

What the shell should do for this compaction check.

ToolDecision

Decision returned by ToolPolicy::before_call to control tool execution.

TurnOutcome

Outcome of a single turn (one LLM interaction).

UserEvent

Plan / user lifecycle event types surfaced to consumers. User-space events produced by tools during execution.

Constants

DEFAULT_SEED_MESSAGE

Default user seed message for new windows (see TokenBudgetConfig::seed_message).

Traits

ApprovalHandler

Trait for handling tool approval requests.

ContextCompaction

Trait for inline context compaction within the react loop.

FocusInput

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

Middleware

PromptFragment

Composable prompt fragment — each fragment owns one concern.

Tool

ToolPolicy

Policy-based control over tool execution.

Functions

build_context_window_info

The window-info system message injected at the start of each window.

compose_fragments

Sort fragments by priority (ascending) and concatenate with double newlines.

create_provider

LLM provider factory (resolves protocol/client from an llm_trait config). Create a provider from configuration.

estimate_messages_tokens

Estimate total tokens across a message list using ContextWindowManager::message_tokens.

first_system_prompt

Find the first non-ephemeral System message (the system prompt).

format_number

Format a number with K/M suffixes for display.

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.

token_budget_base_overhead

Token estimate of the fixed content every window starts with: system prompt + window info + guidance + seed (no thread hint — the best case; app-provided hints add on top).

try_load_metrics

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

Type Aliases

AgentResult