Extend protoAgent
protoAgent is a template repo, so the honest answer to "how do I change it" depends on what you're changing:
- Your agent's persona, prompts, and domain logic → fork it. That's what a fork is for (Fork the template).
- A capability — a tool, an integration, a console surface, a background worker → write a plugin. No fork, nothing to keep merging, and it installs from a git URL.
- An untrusted third-party tool → connect an MCP server. Out-of-process, so it doesn't run with the agent's privileges.
This page is the map for the middle one.
Start here
| Never written one | Build your first plugin — twenty minutes to a tool and a console view on a running agent |
| Want the model first | Plugin architecture — what's trusted, what's sandboxed, when your code runs |
| Building something specific | Plugins guide — the contract, seam by seam |
| Need a signature | Reference — generated from the code, so it's current |
What a plugin can contribute
Every one of these is a register_* call in your plugin's register(registry) (full list):
| Tools the agent can call | register_tool · first tool |
| Console views in the left rail | views: in the manifest · building a view · wire protocol |
| HTTP routes, including inbound webhooks | register_router · public paths |
| Background surfaces — a gateway, a poller, an engine loop | register_surface · resuming across reloads |
| Skills and workflows | register_skill_dir · register_workflow_dir · skills · workflows |
| Subagents | register_subagent · subagents |
| Middleware around the model call | register_middleware · middleware |
Chat commands (/yours) | register_chat_command · slash commands |
| Goal & watch verifiers | register_goal_verifier · goal mode · watches |
| Your queue in the agent's own work list | register_work_provider · autonomous operating model |
| Knowledge backends & embedders | register_knowledge_store · register_embedder · knowledge |
| Managed MCP servers | register_mcp_server · MCP |
| A chat bot on a messaging platform | communication plugins |
Plus its own config, secrets, and Settings UI (ADR 0019), and events other plugins can subscribe to without importing it (ADR 0039).
Reference
Generated from the source on every build, and CI-gated — a new seam can't ship undocumented.
| Page | Contents |
|---|---|
| Plugin manifest | Every protoagent.plugin.yaml field — type, default, meaning |
| Registry API | Every register_* seam with its signature, plus registry.host |
| Plugin SDK | graph.sdk — subagents, knowledge, watches, background jobs, scheduling, metrics |
| View bridge | The sandboxed-iframe postMessage protocol |
| Event bus topics | Every topic core publishes, with payload keys and matching rules |
| Testkit | load_plugin, FakeRegistry, host stubs |
| Plugin CLI | python -m server plugin … |
Ship it
| Test it | The testkit runs your real modules with no protoAgent installed — plugin new --tests scaffolds the suite and a CI workflow |
| Publish it | Install & publish plugins — git URLs, pinning, plugins.lock |
| Group several | Bundles — one install for a whole capability stack |
| Extend the console itself | Frontend extension registries for fork-level UI work |