API Reference

Top-Level Functions

agent_loop()

#![allow(unused)]
fn main() {
pub async fn agent_loop(
    prompts: Vec<AgentMessage>,
    context: &mut AgentContext,
    config: &AgentLoopConfig,
    tx: mpsc::UnboundedSender<AgentEvent>,
    cancel: CancellationToken,
) -> Vec<AgentMessage>
}

Start an agent loop with new prompt messages. Returns all messages generated during the run.

agent_loop_continue()

#![allow(unused)]
fn main() {
pub async fn agent_loop_continue(
    context: &mut AgentContext,
    config: &AgentLoopConfig,
    tx: mpsc::UnboundedSender<AgentEvent>,
    cancel: CancellationToken,
) -> Vec<AgentMessage>
}

Resume from existing context. The last message must not be an assistant message.

default_tools()

#![allow(unused)]
fn main() {
pub fn default_tools() -> Vec<Arc<dyn AgentTool>>
}

Returns: BashTool, ReadFileTool, WriteFileTool, EditFileTool, ListFilesTool, SearchTool.

Agent Trait

The runtime interface for all agent implementations. Programs against this trait to remain independent of the specific implementation.

#![allow(unused)]
fn main() {
use phi_core::Agent;  // trait must be in scope to call trait methods
}

Trait methods cover: prompting (prompt, prompt_messages, prompt_with_sender, prompt_messages_with_sender, continue_loop, continue_loop_with_sender), state access (messages, is_streaming, agent_id, session_id, last_loop_id), message mutation (clear_messages, append_message, replace_messages, save_messages, restore_messages, set_tools), control (abort, reset), and steering/follow-up queues (steer, follow_up, clear_steering_queue, clear_follow_up_queue, clear_all_queues, set_steering_mode, set_follow_up_mode).

The trait is object-safe: Box<dyn Agent> and &mut dyn Agent work for runtime polymorphism.

phi_core::* re-exports Agent, so use phi_core::* brings it into scope automatically.

BasicAgent Struct

The default in-memory Agent implementation. Owns a single linear message history, tool registry, and model configuration.

Construction

#![allow(unused)]
fn main() {
let api_key = std::env::var("ANTHROPIC_API_KEY").unwrap();
let agent = BasicAgent::new(ModelConfig::anthropic(
    "claude-sonnet-4-20250514",
    "Claude Sonnet 4",
    &api_key,
));
}

Builder Methods

All return Self for chaining (unless noted as Result).

Core

Tools & Integrations

Workspace & System Prompt

Context & Limits

Behavior

Callbacks

Prompting

State Access

State Mutation

Steering & Follow-Up Queues

Control

Session Callback Types

These are set on SessionRecorderConfig and fire at the session level (not per-loop). See Sessions for usage.

Re-exports

The crate re-exports key types from lib.rs:

#![allow(unused)]
fn main() {
// Agent system
pub use agents::{Agent, AgentProfile, BasicAgent, QueueMode};
pub use agents::SubAgentTool;

// Agent loop
pub use agent_loop::{agent_loop, agent_loop_continue, agent_loop_parallel};
pub use agent_loop::evaluation::{
    ElaborateEvaluation, LlmJudgeEvaluation, PickFirstEvaluation,
    TokenEfficientEvaluation, TransparentEvaluation,
};

// Config-driven construction
pub use config::{
    agent_from_config, agent_from_config_with_registry, agents_from_config,
    parse_config, parse_config_file, AgentConfig, ConfigError, ConfigFormat,
};

// Context management
pub use context::{
    CompactionStrategy, CompactionConfig, CompactionScope, ContextConfig,
    DefaultCompaction, DefaultBlockCompaction, BlockCompactionStrategy,
    ContextTracker, CompactionBlock, CompactedSection, TurnMap, TurnRange,
    build_context_from_session, compact_session_loops,
};
pub use context::skills::SkillSet;

// Session persistence
pub use session::{
    Session, SessionRecorder, SessionRecorderConfig, SessionScope, SessionError,
    LoopRecord, LoopEvent, LoopStatus, Turn, LoopConfigSnapshot,
    ParallelGroupRecord, ChildLoopRef, SpawnRef, SessionFormation,
    save_session, load_session, list_session_ids, delete_session, load_sessions_for_agent,
};

// Provider
pub use provider::retry::RetryConfig;

// Types (glob re-export)
pub use types::*;  // Message, Content, AgentMessage, AgentEvent, Usage, LlmMessage,
                    // StopReason, StreamDelta, TurnTrigger, ThinkingLevel, CacheConfig, etc.
}

0.7.0 additions (reachable via module paths)

These symbols were added in 0.7.0 but are not (yet) part of the top-level glob. Import them via their module path:

#![allow(unused)]
fn main() {
// Session: trait-based pluggable store + atomic-write filesystem impl with
// advisory locks (fs2 exclusive lock; returns SessionError::Locked on contention).
use phi_core::session::{SessionStore, FileSystemSessionStore};

// Provider: credential refresh hook for long-running agents whose token expires
// mid-run. On ProviderError::Auth, the loop invalidates the cached credential
// and retries once before propagating.
use phi_core::provider::{CredentialProvider, StaticCredentialProvider};

// Provider: structured-output contract. JsonObject = free-form JSON;
// JsonSchema = strict schema (native where supported, tool-call emulation on
// Anthropic and Anthropic-on-Bedrock, SchemaMismatch on others).
use phi_core::provider::ResponseFormat;

// Agent: fallible build_config(). Default impl returns Err(MissingModelConfig)
// instead of panicking when model_config() is None.
use phi_core::agents::AgentBuildError;

// MCP: configurable per-request timeout (default 30s) on both stdio + HTTP
// transports. Use McpClientConfig with connect_stdio_with_config /
// connect_http_with_config.
use phi_core::mcp::{McpClientConfig, DEFAULT_REQUEST_TIMEOUT};
}