Struct PhiAgent 

pub struct PhiAgent {
    pub config: PhiAgentConfig,
    /* private fields */
}

A built Agent instance.

Wraps AgentRuntime with common operations behind a simpler API.

Example

let agent = PhiAgent::build(builder, config)?;
let session = agent.create_session().await;
agent.run_turn(session, "Hello!", |event| renderer.render(event)).await?;

Fields

config: PhiAgentConfig

The configuration this agent was built with.

Implementations

impl PhiAgent

pub fn builder( llm_client: Arc<dyn StreamClient>, system_prompt: String, ) -> AgentBuilder

Create a pre-configured AgentBuilder.

Equivalent to base_agent_builder(llm_client).system_prompt(system_prompt), after which you register tools, middleware, and approval handlers, then call Self::build.

pub fn build(builder: AgentBuilder, config: PhiAgentConfig) -> AgentResult<Self>

Build from an AgentBuilder.

pub async fn create_session(&self) -> SessionId

Create an agent session.

pub async fn run_turn<F>( &self, session_id: SessionId, query: &str, on_event: F, ) -> AgentResult<RunOutcome>

where F: FnMut(RuntimeEvent) -> AgentResult<()> + Send,

Execute one turn.

pub fn cancel(&self)

Cancel the currently executing turn.

pub fn is_cancelled(&self) -> bool

Check whether the agent has been cancelled.

pub async fn set_reasoning_effort(&self, effort: ReasoningEffort)

Set the reasoning effort.

pub fn runtime(&self) -> &AgentRuntime

Access the underlying runtime (for advanced use like hook registration).

pub async fn list_tools(&self) -> Vec<ToolMetadata>

List all registered tools with their metadata, sorted by name.

impl PhiAgent

pub async fn attach_mcp(&self, config: McpServerConfig) -> AgentResult<()>

Dynamically attach an MCP server at runtime.

Adds the server config, connects, discovers tools, and registers them into the agent’s [ToolRegistry]. Tools are registered with the mcp.<server_name>.<tool_name> naming convention.

Returns an error if the server cannot be connected or tools cannot be discovered. On failure, the server config is rolled back (removed from the hub) so a partial entry is never left behind.

Performance note

Currently calls hub.register_all() which re-registers all servers’ tools (O(total-servers)). For the common case this is fine because re-registration is a no-op HashMap insert. A future optimization would register only the newly attached server’s tools.

pub async fn detach_mcp(&self, name: &str)

Dynamically detach an MCP server at runtime.

Unregisters all tools belonging to this server from the agent’s [ToolRegistry], disconnects the server, and removes its config from the hub.

This is a no-op if the server is not attached.

Concurrency note

There is a TOCTOU window between collecting tool names (read lock) and removing them (write lock). If another thread re-attaches a server with the same name during this window, its tools may be prematurely removed. In practice this race is harmless: the new attach will re-register tools on the next turn, and tool calls in flight will fail with a clear error since hub.remove_server disconnects clients.

pub fn into_mcp_server(&self, config: McpServeConfig) -> McpServer

Convert this agent into an MCP server that external orchestrators can call.

Trait Implementations

impl Clone for PhiAgent

fn clone(&self) -> PhiAgent

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.