Agent

Instructions

Set an agent's system prompt and project rules, and add context to a single prompt.

An agent’s system prompt is built from prompt sections. Your extensions add sections that every conversation gets, and a conversation can add its own instructions after them. The agent renders the system prompt again before every model call.

Sections for every conversation

Add sections with an extension. Sections come in the order the extensions are installed.

import { createRegistry, defineExtension, section } from "@earendil-works/pi-durable";
import { CodingTools } from "@earendil-works/pi-durable/tools";
import { pi } from "@rivet-dev/pi";
import { e2bProvider } from "@rivet-dev/sandbox-adapter/e2b";
import { setup } from "rivetkit";

const extensions = createRegistry();
extensions.install(CodingTools);
extensions.install(
	defineExtension({
		name: "payments-team",
		sections: [
			section("role", () => "You review pull requests for the payments team. Be brief and cite file paths."),
			section("project-rules", () => "Run `npm test` before proposing a fix. Never edit files in `migrations/`."),
			// The skill files are in the sandbox. This section tells the model where to find them.
			section("skills", () => "The `skills/` folder has one folder per skill. Read a skill's SKILL.md before you start a task it covers."),
		],
	}),
);

const agent = pi({
	model: "anthropic/claude-opus-5-5",
	registry: extensions,
	sandbox: e2bProvider(),
});

export const registry = setup({ use: { agent } });

registry.start();

The model gets the payments-team sections as tagged blocks:

<role>
You review pull requests for the payments team. Be brief and cite file paths.
</role>
<project-rules>
Run `npm test` before proposing a fix. Never edit files in `migrations/`.
</project-rules>
<skills>
The `skills/` folder has one folder per skill. Read a skill's SKILL.md before you start a task it covers.
</skills>

The agent runs each section’s function again before every model call. A section can return text that changes, such as the current date or a value from your database.

Instructions for one conversation

Call conversation.configure(id, { instructions }) to give one conversation its own instructions. They go after every extension section, and they apply from the next model call. Pass instructions: null to remove them.

Context for one prompt

Put context for a single turn in the prompt itself. The prompt action takes a string, or an array of text and image blocks. Each image is { type: "image", data, mimeType }, with the image base64-encoded in data. The system prompt stays the same.

import { readFile } from "node:fs/promises";
import { createClient } from "rivetkit/client";
import type { registry } from "./server";

const client = createClient<typeof registry>();
const agent = client.agent.getOrCreate(["payments", "pr-482"]);

// Instructions for this conversation only. They go after the extension sections.
const root = await agent.harness.root();
await agent.conversation.configure(root.id, {
	instructions: "This conversation is about pr-482 in https://github.com/acme/payments. Focus on the checkout flow.",
});

// Context for one prompt goes in the prompt itself, text and images.
const screenshot = await readFile("checkout-error.png");
const result = await agent.prompt([
	{ type: "text", text: "Clone the repository and check out pr-482. This error shows up at checkout after that PR. Which change causes it?" },
	{ type: "image", data: screenshot.toString("base64"), mimeType: "image/png" },
]);

console.log(result.status === "done" ? result.text : `Unanswered: ${result.reason}`);

AGENTS.md and skills

Pi doesn’t support AGENTS.md files or skills yet. Use these workarounds:

Project rules: put the rules of your AGENTS.md in a section, as project-rules does above, or in a conversation’s instructions.
Skills: put the skill files in the agent’s workspace, such as the sandbox or the files in the Actor’s database. Then add a section that tells the model where the skills are and to read one before it acts, as skills does above.