Agent Core

Core agent runtime for building agentic applications

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)

options · AgentOptions

Show properties

initialState · Partial<AgentState>

Initial state (system prompt, model, tools, etc.)

convertToLlm · function

Convert AgentMessage[] to Message[] for LLM. Default filters to user/assistant/toolResult.

transformContext · function

Transform context before LLM call (for pruning, injection, etc.)

steeringMode · 'all' | 'one-at-a-time'

How to send steering messages. Default: 'all'

followUpMode · 'all' | 'one-at-a-time'

How to send follow-up messages. Default: 'all'

streamFn · StreamFn

Custom stream function (for proxies). Default: streamSimple

sessionId · string

Session identifier for caching

getApiKey · function

Dynamically resolve API key for each call

thinkingBudgets · ThinkingBudgets

Custom token budgets for thinking levels

Properties

state · AgentState

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

signal · AbortSignal

Abort signal for cancellation

Returns an event stream that emits agent events and resolves to new messages.

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[]>

prompts · AgentMessage[] · required

User messages to add to context

context · AgentContext · required

Current conversation context

Show properties

systemPrompt · string · required

System prompt

messages · AgentMessage[] · required

Conversation messages

tools · AgentTool[] · required

Available tools

config · AgentLoopConfig · required

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[]>

Used for retries when the last message is a user message or tool result.

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

systemPrompt · string

System prompt defining agent behavior

model · Model

Current LLM model

thinkingLevel · ThinkingLevel

Reasoning intensity level

tools · AgentTool[]

Available tools

messages · AgentMessage[]

Conversation history

isStreaming · boolean

Whether agent is currently streaming

streamMessage · AgentMessage | null

Current streaming message (if any)

pendingToolCalls · Set<string>

Tool call IDs awaiting execution

error · string

Last error message (if any)

Agent Tool

Tool definition for the agent.

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

name · string · required

Unique tool name

description · string · required

Description for the LLM

parameters · TSchema · required

TypeBox schema for parameters

execute · function · required

Execute the tool and return result

AgentToolResult

interface AgentToolResult<T> {
  content: (TextContent | ImageContent)[];
  details: T;
}

content · Content[]

Content to send to LLM

details · T

Metadata for UI/logging (not sent to LLM)

Events

The agent emits events during execution:

• agent_start - Agent turn begins
• agent_end - Agent turn completes
• turn_start - Turn starts
• turn_end - Turn ends
• message_start - Message added to context
• message_update - Streaming message delta
• message_end - Message complete
• tool_execution_start - Tool execution begins
• tool_execution_update - Tool execution progress
• tool_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");
});