01 // AI agents

The minimal agent runtime

The Pi fragment is built on top of the Workflows fragment, and provides a minimal runtime for agent turns. Sessions are automatically durable, and tool calls are automatically replayed.

Install

npm install @fragno-dev/pi-fragment @fragno-dev/workflows @fragno-dev/db

npm install @fragno-dev/pi-fragment @fragno-dev/workflows @fragno-dev/db

Depends on

Workflows + DB

Best for

Embedding agents

Capabilities

Durable sessions

Every turn runs through workflows, so agent state survives retries and restarts.

Deterministic tool replay

Tool calls are captured and replayed, so side effects do not run twice.

Typed session APIs

Create sessions, inspect runs, and send messages from framework-native clients.

Interface

Pi keeps the route surface small. The complexity lives in durable execution semantics, not in transport sprawl.

Route surface

POST /sessions
GET  /sessions
GET  /sessions/:sessionId
GET  /sessions/:sessionId/active
POST /sessions/:sessionId/messages

POST /sessionsGET  /sessionsGET  /sessions/:sessionIdGET  /sessions/:sessionId/activePOST /sessions/:sessionId/messages

Why it matters

Agent features fail when state and side effects are implicit. Pi makes both explicit: sessions are queryable records, tool calls are replayable history, and clients consume typed hooks instead of bespoke chat plumbing.

Blueprint

Define the agent once, then integrate the product around it.

Create the server

import { defaultFragnoRuntime } from "@fragno-dev/core";
import { createPi, createPiFragment, defineAgent } from "@fragno-dev/pi-fragment";
import { createWorkflowsFragment } from "@fragno-dev/workflows";

const pi = createPi()
  .agent(
    defineAgent("support-agent", {
      systemPrompt: "You are a helpful support agent.",
      model,
      tools: ["search"],
    }),
  )
  .tool("search", async () => ({
    name: "search",
    description: "Lookup references",
    inputSchema: { type: "object", properties: { query: { type: "string" } } },
    handler: async ({ query }: { query: string }) => "Result for " + query,
  }))
  .build();

const workflowsFragment = createWorkflowsFragment(
  {
    workflows: pi.workflows,
    runtime: defaultFragnoRuntime,
  },
  { databaseAdapter, mountRoute: "/api/workflows" },
);

export const fragment = createPiFragment(
  pi.config,
  { databaseAdapter, mountRoute: "/api/pi" },
  { workflows: workflowsFragment.services },
);

import { defaultFragnoRuntime } from "@fragno-dev/core";import { createPi, createPiFragment, defineAgent } from "@fragno-dev/pi-fragment";import { createWorkflowsFragment } from "@fragno-dev/workflows";const pi = createPi()  .agent(    defineAgent("support-agent", {      systemPrompt: "You are a helpful support agent.",      model,      tools: ["search"],    }),  )  .tool("search", async () => ({    name: "search",    description: "Lookup references",    inputSchema: { type: "object", properties: { query: { type: "string" } } },    handler: async ({ query }: { query: string }) => "Result for " + query,  }))  .build();const workflowsFragment = createWorkflowsFragment(  {    workflows: pi.workflows,    runtime: defaultFragnoRuntime,  },  { databaseAdapter, mountRoute: "/api/workflows" },);export const fragment = createPiFragment(  pi.config,  { databaseAdapter, mountRoute: "/api/pi" },  { workflows: workflowsFragment.services },);

Create a client

import { createPiFragmentClient } from "@fragno-dev/pi-fragment/react";

const pi = createPiFragmentClient({ baseUrl: "/api/pi" });

const { data: sessions } = pi.useSessions();
const createSession = pi.useCreateSession();
const sendMessage = pi.useSendMessage();

import { createPiFragmentClient } from "@fragno-dev/pi-fragment/react";const pi = createPiFragmentClient({ baseUrl: "/api/pi" });const { data: sessions } = pi.useSessions();const createSession = pi.useCreateSession();const sendMessage = pi.useSendMessage();

Use it

const session = await createSession.mutate({
  body: { agent: "support-agent", title: "Customer issue" },
});

await sendMessage.mutate({
  path: { sessionId: session.id },
  body: { text: "Summarize the bug report and propose next steps." },
});

const session = await createSession.mutate({  body: { agent: "support-agent", title: "Customer issue" },});await sendMessage.mutate({  path: { sessionId: session.id },  body: { text: "Summarize the bug report and propose next steps." },});

Outcome

Built to survive real runtime conditions.

Long-running turns

Pause, resume, and recover work without losing context.

Safe side effects

Replays reuse captured tool results instead of re-running risky actions.

Inspectable state

Sessions and messages remain queryable, not trapped in ephemeral runtime memory.