Pi agent

agentak/pi is Agentak's included agent runtime. It combines pi-agent-core with browser provider selection, model catalogs, thinking levels, tool approvals, storage, history, usage, and user-facing errors.

The loop runs in the page. It can run an on-device model or send a request directly to a supported provider. Agentak does not require its own backend.

This is the only Agentak entry that loads Pi. A custom ChatSession can use the same UI without importing it.

#Create a session

import { createPiSession } from "agentak/pi";

const session = createPiSession();

// Pass session to ChatPanel, AgentChat, or mountChat().
// End it when the host no longer needs it.
session.dispose();

Create the session once, outside a render function. A fresh session starts on the first provider in the picker, with no model. If the user sends a message first, Agentak holds it, opens settings, and sends it after a usable model is selected.

A configured session can start with instructions, tools, persistence, and a preferred provider:

import { browserStorage, createPiSession } from "agentak/pi";

const session = createPiSession({
  provider: "openrouter",
  apiKey: "sk-or-v1-…",
  storage: browserStorage(),
  history: true,
  page: true,
  thinkingLevel: "medium",
  systemPrompt: "You are the support agent for example.com. Keep answers short.",
  approvals: "once",
});

#How it reaches the widget

message
  -> Pi Agent
  -> provider stream or on-device model
  -> agent events
  -> Agentak transcript, queue, approvals, usage, and errors
  -> ChatSession
  -> AgentChat / ChatPanel

The session rebuilds the visible transcript from Pi state after every event. Reasoning, text, tool calls, results, images, failed turns, and compaction checkpoints become the parts rendered by the chat.

#Options

PiSessionOptions includes these high-level session options and the agent options below:

The thinking scale is off, minimal, low, medium, high, xhigh, and max. Agentak clamps the current choice to the levels the selected model supports. A model with no reasoning support uses off and shows no thinking-level control.

#PiSession methods

createPiSession() returns a PiSession. It implements the complete ChatSession contract and adds:

• ready resolves once the store has answered with the keys, the provider, the model, the level, and any stored conversations. Wait for it to mount without showing a chat that has forgotten its choices.
• save() returns a versioned PiSnapshot. It is cheap and safe while a turn streams; the unfinished turn is not included.
• restore(snapshot?) replaces the live conversation in place. With no snapshot, it starts a new conversation. A running turn is stopped first.
• dispose() removes listeners and releases session resources.

The UI never calls dispose(). The code that created the session must call it.

#Explore the Pi runtime