Advanced Pi API

Most applications should use createPiSession(). The agentak/pi entry also exports the layers underneath it for hosts that want Pi with a different picker, store, or surface.

#Agent and store

import { createAgent, createAgentStore } from "agentak/pi";

const runtime = createAgent({
  systemPrompt: "Answer from the supplied tools.",
  tools,
  approvals: "once",
});

const store = createAgentStore(runtime);
const unsubscribe = store.subscribe(() => {
  render(store.snapshot());
});

store.send("What is on this page?");

// Later:
unsubscribe();
store.dispose();

createAgent() creates Pi's Agent and its approval gate. It uses the default LLM7 model until a host sets another model. It does not add provider settings or history.

createAgentStore() converts agent events into an identity-stable snapshot with visible messages, streaming state, errors, usage, model, thinking level, and queued messages. It also supplies send, stop, reset, load, retry, approval response, queue removal, model selection, and thinking-level selection.

useAgent(runtime) exposes the same store behavior as a Preact hook and disposes its store when the component unmounts.

#Providers and catalogs

Use these exports to build a custom picker:

• PROVIDERS, availableProviders(), findProvider(), and corsFree()
• SUPPORTED_APIS and streamFor()
• loadCatalog(), cachedCatalog(), catalogModels(), and findModel()
• useCatalogSource() for bundled, offline, or policy-restricted catalogs
• default provider and model constants

streamFor() reads the API family from the selected model and imports only that stream module. A provider-specific fetch adapter can rewrite requests where browser CORS requires it.

#Storage, snapshots, and history

• memoryStorage(), browserStorage(), pageStorage, and createChoices()
• readPiSnapshot(), usablePiMessages(), version and field constants
• createHistory(), mintConversationId(), and the PiHistory types

Always pass stored JSON through readPiSnapshot() before using it. usablePiMessages() removes a trailing failed turn and cuts a transcript at an unanswered tool call, because providers reject that incomplete sequence.

#Transcript and errors

• toViewMessages() converts Pi messages to Agentak ViewMessage objects.
• toContextUsage() builds token, cost, context-window, and near-limit data.
• describeFailure() creates user-facing provider error text.
• failureStatus() extracts a leading HTTP status for control flow.
• generateTitle(), titleRequest(), toTitle(), and useTitle() provide title behavior.

These helpers are useful when a host runs Pi but drives ChatView instead of using a ChatSession.

#Approvals

createApprovalGate(policy, approvalFor?) returns:

• beforeToolCall() for Pi's agent hook
• pending() and answers() for rendering state
• respond() to allow or deny a call
• subscribe() for updates
• clear() to deny pending work and reset remembered approvals

Read Tools and approvals for policy behavior.

#Page tools and WebMCP

The page-tool layer is independent of the current document:

• documentTools() creates a PageTools source for document.modelContext.
• createPageToolset() turns any PageTools source into Pi tools and approval rules.
• pageToolName() normalizes names for providers.
• toToolContent() reads plain JSON or MCP-shaped text/image results.
• modelContext(), webmcpSupported(), and toPageTool() expose the browser adapter.

This split lets an iframe, worker bridge, or extension tab provide the serializable half while the source document keeps its live WebMCP objects.

#On-device hooks

Chrome exports include Prompt API capability helpers, model constants, and provider IDs. wllama exports include capability detection, local model metadata, loader URLs, and useWllamaSource().

Read On-device models before replacing loaders or model metadata.

#When to stay at the session layer

Use createPiSession() when you want Agentak's settings, key flow, provider filtering, catalog loading, error routing, history, and title behavior. The lower-level APIs are not a second setup shortcut; they are the pieces for a host that intentionally owns those policies itself.