Agneta

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 ACPWith Agneta
TransportUsually stdio to an agent process the client startsA 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 connectWhoever starts the processApps the user approved. Pairing gives your app a token, sent in initialize
Which provider, engine and modelThe agent’s own configurationThe 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 touchWhatever the agent process can reachA policy you send with each session (tools, folders, network, approval, limits), enforced by sandboxes, or refused
AfterwardsNothing standardUsage 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.
  • tools is app-only (only your MCP tools), read (plus reading files) or workspace (plus editing and a shell confined to cwd).
  • A policy Agneta can’t enforce is refused with -32602 and data.agneta.unenforceable naming 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.
  • engine is optional: without it, the provider’s defaultEngine. One that’s still downloading answers -32015 with its progress; try again shortly.
  • configOptions are the engine’s own settings. Find the model and reasoning effort by their ACP categories, model and thought_level (each engine names them differently), and change them with session/set_config_option.
  • capabilities tells 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 toSend
Add input to the running turnagneta/steer {"sessionId", "prompt"}
Stop the turnsession/cancel (a notification)
Change model or effort between turnssession/set_config_option {"sessionId", "configId", "value"}
Change the instructions between turnsagneta/instructions/set
Reopen a task after a restartsession/load (pass your MCP servers again: bearers are per session)
Ask about a finished task without changing itagneta/fork
Read the task’s trace from any pointagneta/trace/read {"sessionId", "after"}
End itsession/close

Messages your app should handle

From AgnetaMeaning, 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.needsSignInThe provider must sign in again; ask the user to open Agneta
-32011A turn is already running in this session: steer it, or wait
-32012Too many turns are waiting; try again shortly
-32013The user paused this provider
-32015The engine is still downloading (data.agneta.engineDownloading, with progress); try again shortly
-32014This 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.

This page is README.md, “For app developers” in the repository, on main. History