Skip to main content

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 a stateful agent runtime built on top of the unified LLM API. It handles tool execution, message queuing, and streaming events for building interactive AI agents.

​
Key Features

Stateful Runtime

Manages conversation state, tools, and model configuration

Tool Execution

Automatic tool calling with validation and error handling

Event Streaming

Real-time events for UI updates during agent operations

Message Queuing

Steering and follow-up message queues for interruptions

​
Quick Start

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-sonnet-4-20250514"),
  },
});

agent.subscribe((event) => {
  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
    process.stdout.write(event.assistantMessageEvent.delta);
  }
});

await agent.prompt("Hello!");

​
Core Concepts

​
Agent State

The agent maintains state including:
  • System prompt - Instructions for the LLM
  • Model - Active LLM model
  • Thinking level - Reasoning depth
  • Tools - Available functions
  • Messages - Conversation history
  • Stream status - Current streaming state

​
Message Types

The agent works with AgentMessage, which can include:
  • Standard LLM messages (user, assistant, toolResult)
  • Custom app-specific message types via declaration merging
The convertToLlm function filters and transforms messages before LLM calls.

​
Event Flow

The agent emits granular events for UI updates: 
prompt("Hello")
├─ agent_start
├─ turn_start
├─ message_start { userMessage }
├─ message_end { userMessage }
├─ message_start { assistantMessage }
├─ message_update { partial... }
├─ message_end { assistantMessage }
├─ turn_end
└─ agent_end
See the Transport and State Management pages for more details on advanced features.

​
Installation

npm install @mariozechner/pi-agent-core

​
Next Steps

Transport

Custom backends and proxy usage

State Management

Managing agent state and message queues

API Reference

Complete Agent class API documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us