Agent Core Overview

Stateful agent runtime with tool execution and event streaming

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

Basic Usage

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

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