Crate phi_agent 

phi-agent: General-purpose AI Agent framework

Built on agent-base and agent-works, providing builder factory, renderer, config resolution, session management, and other infrastructure. Does not bundle any tools — tools are injected by consumers.

Re-exports

pub use agent::CompressionConfig;

pub use agent::PhiAgent;

pub use agent::PhiAgentConfig;

pub use agent::SummarizingMiddleware;

pub use agent::base_agent_builder;

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;

Modules

agent

Agent construction and lifecycle management.

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

render

session

Structs

AgentBuilder

AgentRuntime

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.

OpenAiClient

PlanItem

A single step in a lightweight plan checklist.

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.

ToolOutput

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.

Enums

AgentError

FocusError

Error type for Focus calls.

PlanStepStatus

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

ReasoningEffort

Reasoning intensity/depth enumeration.

RunOutcome

The final outcome of an Agent 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).

ToolControlFlow

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

Tool

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