agent-capabilities

Agent capabilities

Every capability is a native Pi tool or extension that you hand to defineAgent (from @hachej/boring-agent/agents). The host decides what the agent may do. Start from the server in the build-agent-app skill.

const agent = defineAgent({
  id: 'writer', model: { provider: 'openai', modelId: 'gpt-5-mini' }, instructions: '...',
  tools: [/* tool registrations */],
  extensions: [/* native extensions, in order */],
  delegates: [/* sub-agents */],
});
agent.install(registry);   // before Harness.open

Custom tools

Use Pi's defineTool and Type. Return text in output.

import { defineTool } from '@earendil-works/pi-durable';
import { Type } from '@earendil-works/pi-ai';

const lookupOrder = defineTool({
  name: 'lookup_order', description: 'Look up a fictional order by its number.',
  parameters: Type.Object({ number: Type.String() }, { additionalProperties: false }),
  execute: async ({ number }) => ({ output: [{ type: 'text', text: JSON.stringify(await orders.get(number)) }] }),
});

The host's execute owns the data access, credentials and limits. For a tool described by a raw JSON Schema (an MCP inputSchema), use jsonSchemaTool({ name, description, parameters, execute }) from /agents.

Files

• Give the agent Pi's own createReadTool(), createWriteTool(), createEditTool() (and createBashTool() with a shell) from @earendil-works/pi-durable/tools, in one defineExtension.
• Add createFileGuard({ workspace: { files, root, access } }) from /file-guard after that extension. It routes read/write/edit through the workspace provider, refuses writes to files the conversation has not read at their current revision, and records agent edits in file history.
• Add createPresentTool({ workspace }) from /artifacts so the agent can open a file in the page.
• Use the same files provider everywhere (guard, present, revision route). Never a second copy.
• Several people, one agent: resolve the workspace per call with @hachej/boring-agent/workspaces (Workspace per call).