Pi

Quick start

server.tsclient.ts

server.ts

import { agentOs } from "rivetkit/agent-os";
import { setup } from "rivetkit";
import pi from "@agentos-software/pi";

const vm = agentOs({
  options: { software: [pi] },
});

export const registry = setup({ use: { vm } });
registry.start();

client.ts

import { createClient } from "rivetkit/client";
import type { registry } from "./server";

const client = createClient<typeof registry>("http://localhost:6420");
const agent = client.vm.getOrCreate(["my-agent"]);

const session = await agent.createSession("pi", {
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
});

const { text } = await agent.sendPrompt(
  session.sessionId,
  "What files are in the current directory?",
);
console.log(text);

Read Sessions first for session options, streaming events, prompts, and lifecycle management.

Extensions

Pi supports extensions that let you register custom tools, modify the system prompt, and hook into agent lifecycle events. Write a .js file into the VM’s extensions directory before creating a session and Pi discovers it automatically.

Pi scans two directories for .js extension files:

Directory	Scope
~/.pi/agent/extensions/	Global — applies to all Pi sessions
<cwd>/.pi/extensions/	Project — applies only when cwd matches

const extensionCode = `
export default function(pi) {
  // Modify the system prompt before each agent turn
  pi.on("before_agent_start", async (event) => {
    return {
      systemPrompt: event.systemPrompt +
        "\\n\\nAlways respond in formal English."
    };
  });
}
`;

// Write the extension before creating the session
await agent.mkdir("/home/agentos/.pi/agent/extensions", { recursive: true });
await agent.writeFile("/home/agentos/.pi/agent/extensions/formal.js", extensionCode);

// Pi discovers the extension automatically
const { sessionId } = await agent.createSession("pi", {
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY },
});

See the Pi extension documentation for the full extension API.

Customizing the agent

Pi is a built-in agent, but it’s just a software package under the hood. To ship your own ACP adapter, swap the underlying agent SDK, or register a tweaked Pi build as a new agent, see Custom Agents.