For app developers
Try the Project Chat example. This small Electron app pairs with Agneta, keeps its access and reconnects by itself, offers to open Agneta when it isn’t running, lets you choose Agneta or Agneta Dev, lets you pick the provider, engine, model and effort, streams a conversation, and lets the agent propose a note for you to review.
Your app is an ACP client and Agneta is the ACP agent. If your app already speaks ACP, most of what follows is familiar. What Agneta adds is how you reach it, how the user lets your app in, and the rules a task runs under.
| Plain ACP | With Agneta | |
|---|---|---|
| Transport | Usually stdio to an agent process the client starts | A WebSocket on loopback (ws://127.0.0.1:47321/acp, or 47331 for development builds), one JSON-RPC 2.0 message per text frame. Agneta is already running; your app never starts an agent |
| Who may connect | Whoever starts the process | Apps the user approved. Pairing gives your app a token, sent in initialize |
| Which provider, engine and model | The agent’s own configuration | The providers and engines the user allowed your app, picked per session (agneta/access lists them); model and effort through the engine’s own config options |
| What the agent may touch | Whatever the agent process can reach | A policy you send with each session (tools, folders, network, approval, limits), enforced by sandboxes, or refused |
| Afterwards | Nothing standard | Usage in every prompt result, and the task’s full trace, live or later |
No SDK is needed. Any WebSocket and JSON-RPC 2.0 code will do, including in a sandboxed Mac App Store app. That needs com.apple.security.network.client to connect, plus com.apple.security.network.server if the app serves its own MCP tools; its folders come from the user (an open panel or a security-scoped bookmark), since Agneta keeps app containers out of reach (details). To see the whole exchange in Swift, read Sources/agneta-testclient/main.swift, the maintainers’ test client: it pairs, opens a session with a policy and an MCP server, prompts and prints the stream in about 170 lines. It’s a demonstration, not a client library: a real app keeps its token in the Keychain and reconnects with it, as Project Chat does.
The conversation, step by step
1. Connect. Open ws://127.0.0.1:47321/acp, the port of releases; development builds listen on 47331. If the connection is refused, Agneta isn’t running: ask the user whether to open it, and on a yes open agneta://open (agneta-dev://open for development builds), wait for the port and connect. Never open it without asking.
2. Pair, once. Ask to be let in, and show the user that you’re waiting:
→ {"jsonrpc": "2.0", "id": 1, "method": "agneta/pair",
"params": {"name": "Example App", "scope": {"tools": "workspace", "folders": ["/Users/me/Documents/Example Project"]}}}
← {"jsonrpc": "2.0", "id": 1, "result": {"token": "…", "remembered": true, "access": {…}}}
The scope says what your app will need: the most built-in tools, and the user’s folders its sessions will work in. Without one, your app gets its own tools only, in a workspace Agneta makes for it (workspace). Agneta opens its approval window, which shows the scope; the user ticks the providers your app may use (engines are all allowed unless they narrow them) and chooses Allow Once or Always Allow. Every later session must fit the scope. If your app is signed with a Developer ID or App Store certificate, Agneta checks the signature and shows the app as verified. If it isn’t (ad hoc or development builds), Agneta first sends you agneta/pairingCode {"code": "123456"}. Show that code; the user allows your app only if it matches the one in Agneta’s window. When remembered is true (Always Allow), store the token in your Keychain and connect with it next time, without pairing; Allow Once ends with the connection. Pairing again with Always Allow replaces your app’s access rather than adding to it; an unverified app starts afresh, with a new workspace. A refusal comes back as error -32002.
3. Initialize, on every connection.
→ {"jsonrpc": "2.0", "id": 2, "method": "initialize",
"params": {"protocolVersion": 1, "clientCapabilities": {}, "_meta": {"agneta": {"token": "…"}}}}
← {"jsonrpc": "2.0", "id": 2, "result": {"protocolVersion": 1, "agentCapabilities": {…},
"_meta": {"agneta": {"extensions": ["agneta/policy", "agneta/access", "agneta/usage", …],
"access": {"providers": [{"id": "acct-1", "label": "Claude", "kind": "claude", "paused": false,
"engines": ["claude-code", "goose"], "defaultEngine": "claude-code"}],
"engines": [{"id": "claude-code", "name": "Claude Code", "state": "ready", "capabilities": {…}}, …],
"allowedEngines": "all", "scope": {…}, "workspace": "…"}}}}}
access is what your app may use: each provider with the engines its tasks there may run on (default first), and each engine’s state on this Mac (ready, downloading, downloadable, failed or unavailable, with why). agneta/access returns it again at any time, and agneta/accessChanged arrives when it changes. Error -32001 with needsPairing means the user removed your app, or the token is unknown: forget the token, and pair again when the user asks to connect.
4. Start a session in a workspace folder, with your own tools and a policy:
→ {"jsonrpc": "2.0", "id": 3, "method": "session/new", "params": {
"cwd": "/Users/me/Documents/Example Project",
"mcpServers": [{"type": "http", "name": "app", "url": "http://127.0.0.1:52011/mcp",
"headers": [{"name": "Authorization", "value": "Bearer <per-session secret>"}]}],
"_meta": {
"agneta": {"account": "acct-1", "engine": "claude-code"},
"agneta/policy": {"tools": "workspace", "network": "none", "approval": "never-ask",
"limits": {"maxTurns": 100, "maxSeconds": 900}},
"agneta/task": {"title": "Tidying the project notes"},
"agneta/instructions": {"text": "You are Example App's assistant."},
"agneta/trace": {"live": true}}}}
← {"jsonrpc": "2.0", "id": 3, "result": {"sessionId": "s_…", "configOptions": […],
"_meta": {"agneta": {"account": "acct-1", "capabilities": {"engine": "claude-code", "steer": true, "fork": false, …}}}}}
- Your tools are an MCP server (Streamable HTTP) that your app runs on loopback, with a fresh bearer per session. Agneta accepts only loopback HTTP servers and masks the bearer in traces. A session with its own engine may reach exactly those ports; app-only sessions on Goose share one engine per account, and OpenCode runs a private server, so those may reach any loopback port. Your tools run in your app, with your app’s permissions, not inside Agneta’s sandbox.
toolsisapp-only(only your MCP tools),read(plus reading files) orworkspace(plus editing and a shell confined tocwd).- A policy Agneta can’t enforce is refused with
-32602anddata.agneta.unenforceablenaming the field. Examples: an unknown field, a folder containing the home folder, or a cost limit on an engine that can’t report cost while a turn runs. engineis optional: without it, the provider’sdefaultEngine. One that’s still downloading answers-32015with its progress; try again shortly.configOptionsare the engine’s own settings. Find the model and reasoning effort by their ACP categories,modelandthought_level(each engine names them differently), and change them withsession/set_config_option.capabilitiestells you what this session’s engine can do. Offer steering, forking or cost limits only where it says so.
5. Prompt, and stream.
→ {"jsonrpc": "2.0", "id": 4, "method": "session/prompt",
"params": {"sessionId": "s_…", "prompt": [{"type": "text", "text": "Sort these notes by topic."}]}}
← {"jsonrpc": "2.0", "method": "session/update", "params": {"sessionId": "s_…", "update": {"sessionUpdate": "agent_message_chunk", …}}}
← {"jsonrpc": "2.0", "method": "session/update", "params": {"sessionId": "s_…", "update": {"sessionUpdate": "tool_call", …}}}
…
← {"jsonrpc": "2.0", "id": 4, "result": {"stopReason": "end_turn",
"_meta": {"agneta/usage": {"modelCalls": 3, "inputTokens": 5120, "outputTokens": 410, "cost": null,
"costKind": "plan-equivalent", "billing": "subscription", "ms": 8210.4}}}}
The engine’s standard ACP session/update notifications arrive unchanged, under your session id. With "approval": "ask-app", tool permission requests come to you as standard session/request_permission requests. Answer them, and Agneta records your decision in the trace.
6. While it runs and after.
| You want to | Send |
|---|---|
| Add input to the running turn | agneta/steer {"sessionId", "prompt"} |
| Stop the turn | session/cancel (a notification) |
| Change model or effort between turns | session/set_config_option {"sessionId", "configId", "value"} |
| Change the instructions between turns | agneta/instructions/set |
| Reopen a task after a restart | session/load (pass your MCP servers again: bearers are per session) |
| Ask about a finished task without changing it | agneta/fork |
| Read the task’s trace from any point | agneta/trace/read {"sessionId", "after"} |
| End it | session/close |
Messages your app should handle
| From Agneta | Meaning, and what to show |
|---|---|
agneta/accessChanged {"access"} | What your app may use changed: providers or engines added, removed, paused, downloading or ready. Update your pickers |
agneta/queued {"sessionId", "position"} | The provider is busy; the turn waits its place and runs later |
agneta/sessionStopped {"stoppedBy": "user"} | The user pressed Stop in Agneta. Show it as stopped, not as an error |
agneta/sessionStopped {"stoppedBy": "engine"} | The engine ended on its own; resume the task with session/load |
agneta/sessionStopped {"stoppedBy": "limit"} | A policy limit ended the session; load it again to go on |
agneta/rateLimited {"account", "resetsAt"} | The provider’s limit stopped the turn. Retry after resetsAt, or use another provider |
Error with data.agneta.needsSignIn | The provider must sign in again; ask the user to open Agneta |
-32011 | A turn is already running in this session: steer it, or wait |
-32012 | Too many turns are waiting; try again shortly |
-32013 | The user paused this provider |
-32015 | The engine is still downloading (data.agneta.engineDownloading, with progress); try again shortly |
-32014 | This engine can’t do that; check capabilities |
The full reference, with every field, limit and error, is App protocol. Every step there is exercised by Tests/AgnetaKitTests/AppScenarioTests.swift against a real engine.