Documentation Index
Fetch the complete documentation index at: https://mintlify.com/badlogic/pi-mono/llms.txt
Use this file to discover all available pages before exploring further.
The @mariozechner/pi-agent-core package provides the core agent runtime with tool execution, message handling, and state management.
Import
import { Agent, agentLoop, agentLoopContinue } from "@mariozechner/pi-agent-core";
Agent Class
The Agent class manages conversation state, tool execution, and LLM interactions.
Constructor
new Agent(options?: AgentOptions)
Initial state (system prompt, model, tools, etc.)
Convert AgentMessage[] to Message[] for LLM. Default filters to user/assistant/toolResult.
Transform context before LLM call (for pruning, injection, etc.)
How to send steering messages. Default: 'all'
How to send follow-up messages. Default: 'all'
Custom stream function (for proxies). Default: streamSimple
Session identifier for caching
Dynamically resolve API key for each call
Custom token budgets for thinking levels
Properties
Current agent state (read-only)
Methods
prompt
Send a user message and run the agent.
prompt(content: string | Content[], signal?: AbortSignal): EventStream<AgentEvent, AgentMessage[]>
content
string | Content[]
required
User message content
Abort signal for cancellation
continue
Continue the agent from current state (for retries).
continue(signal?: AbortSignal): EventStream<AgentEvent, AgentMessage[]>
updateState
Update agent state.
updateState(update: Partial<AgentState>): void
update
Partial<AgentState>
required
State fields to update
Example
import { Agent } from "@mariozechner/pi-agent-core";
import { getModel } from "@mariozechner/pi-ai";
const agent = new Agent({
initialState: {
systemPrompt: "You are a helpful assistant.",
model: getModel("anthropic", "claude-4.5-sonnet-20250514"),
thinkingLevel: "medium",
tools: [],
messages: [],
},
});
// Send a message
const stream = agent.prompt("What is 2+2?");
// Subscribe to events
stream.on("message_end", (event) => {
console.log("Message:", event.message);
});
// Await result
const newMessages = await stream.result();
console.log("Response:", newMessages);
Agent Loop Functions
Lower-level functions for custom agent implementations.
agentLoop
Start an agent loop with new user message(s).
agentLoop(
prompts: AgentMessage[],
context: AgentContext,
config: AgentLoopConfig,
signal?: AbortSignal,
streamFn?: StreamFn
): EventStream<AgentEvent, AgentMessage[]>
User messages to add to context
Current conversation context
Loop configuration (model, convertToLlm, etc.)
agentLoopContinue
Continue an agent loop from current context.
agentLoopContinue(
context: AgentContext,
config: AgentLoopConfig,
signal?: AbortSignal,
streamFn?: StreamFn
): EventStream<AgentEvent, AgentMessage[]>
Agent State
The agent’s current state.
interface AgentState {
systemPrompt: string;
model: Model<any>;
thinkingLevel: ThinkingLevel;
tools: AgentTool<any>[];
messages: AgentMessage[];
isStreaming: boolean;
streamMessage: AgentMessage | null;
pendingToolCalls: Set<string>;
error?: string;
}
System prompt defining agent behavior
Reasoning intensity level
Whether agent is currently streaming
Current streaming message (if any)
Tool call IDs awaiting execution
Last error message (if any)
interface AgentTool<TSchema extends TSchema = any> {
name: string;
description: string;
parameters: TSchema;
execute: (
toolCallId: string,
args: Static<TSchema>,
signal?: AbortSignal,
updateCallback?: AgentToolUpdateCallback
) => Promise<AgentToolResult<any>>;
}
TypeBox schema for parameters
Execute the tool and return result
interface AgentToolResult<T> {
content: (TextContent | ImageContent)[];
details: T;
}
Metadata for UI/logging (not sent to LLM)
Events
The agent emits events during execution:
agent_start - Agent turn beginsagent_end - Agent turn completesturn_start - Turn startsturn_end - Turn endsmessage_start - Message added to contextmessage_update - Streaming message deltamessage_end - Message completetool_execution_start - Tool execution beginstool_execution_update - Tool execution progresstool_execution_end - Tool execution completes
Example
const stream = agent.prompt("Hello");
stream.on("message_update", (event) => {
if (event.message.role === "assistant") {
console.log("Assistant:", event.message.content);
}
});
stream.on("tool_execution_start", (event) => {
console.log(`Executing tool: ${event.toolName}`);
});
stream.on("agent_end", (event) => {
console.log("Agent finished");
});