A local-first multi-agent app development platform, built on PenguinHarness
title: Agent API description: Let a program talk to one agent over HTTP — turn on the agent's API, mint keys, and run it with curl or the @adelie/amsp client.
The Agent API lets a program outside Adelie — a script, a service, a page in a browser — talk to one agent over HTTP. The program sends its input, reads the run as it happens as an AMSP event stream, and continues the conversation by its Session id. A run uses the Project's models and credentials, is recorded like any other conversation, and appears in the sidebar's Background folder.
Where to go:
- To expose an agent, see Turn on an agent's API.
- To try it from a shell, see Call it with curl.
- To call it from TypeScript, in Node or a browser, see The amsp client.
- For the event stream itself, event by event, see AMSP.
Before you begin
- Only the Project's owner turns an agent's API on or off, chooses its approval mode and manages its keys. Members see the settings.
- The server's administrator can turn the whole Agent API off; it is on by default. See The admin switch.
- A program needs three things, all shown on the agent's API tab:
- the Base URL, the server's address followed by
/api/amsp/v1, such ashttp://localhost:7364/api/amsp/v1for a local server. On a server bound to loopback, which is the default, the address islocalhost:127.0.0.1is where it serves previews, and it answers every API request there with401; - the Agent ID,
<projectId>/<agentId>, such asdemo/coder; - a key, unless the agent allows keyless access.
- the Base URL, the server's address followed by
Turn on an agent's API
- Open the agent's settings (see Agent settings) and select the API tab, at
/agents/<agentId>?tab=api. - Turn on Enable API access.
- Choose the Approval mode for API conversations. See Approval mode.
- Under Keys, select New key, name it and copy the key. It is shown once.
- Copy the Base URL and the Agent ID under Connection. Examples holds a curl command and a TypeScript snippet with both filled in and
$ADELIE_AGENT_KEYin place of the key.
On the Agents page, an agent whose API is on carries an API icon after its name, with the tooltip API access on.
Turning Enable API access off refuses every request for the agent at once with 404 agent_not_found. Its keys and settings are kept for when it is turned back on.
These settings are stored by the server, outside the agent's state, so an agent can neither expose itself nor loosen its own approval mode.
Changing them also takes a person's sign-in. The commands an agent runs carry the server's local API token: it reads these settings, but every change and Try it answer it 403 human_required, and so does the admin switch. This narrows what an agent can do from its own shell; it is not a boundary. A process that runs as the server's OS account outside the sandbox can still sign itself in, so what bounds an agent is its sandbox.
Approval mode
API conversations have their own approval mode, separate from the one the composer preselects:
| Mode | In the selector | What the calling program sees |
|---|---|---|
allow-all (default) |
Approve everything | Every tool call runs; nothing waits on the caller |
read-only |
Approve read-only | Read-only tools run; every other call is sent to the caller as approval.requested and waits for an answer |
always-ask |
Ask every time | Every tool call waits for the caller's answer |
deny-all |
Deny everything | Every tool call is denied; the model reads the denial and carries on without it |
- The mode is read when an API conversation is created and stays with that conversation. A change on the tab applies to API conversations created afterwards. To change one existing conversation, open it in the Web App and change its approval mode there.
- A call that waits is sent to the caller and shown in the conversation in the Web App as well; whichever answers first decides. The run waits with no time limit: until an answer, an abort, or the caller disconnecting, which denies it.
allow-allis the default because the sandbox already bounds what the agent can do, and a program usually has no one to ask. Chooseread-onlyoralways-askwhen the program answers approvals; see Approvals.
An API conversation's sandbox comes from the server's new-chat defaults, as for any new conversation. The Project's preselected approval mode for new conversations does not apply to it.
Keys
- A key is
penguin_followed by 43 characters. It is shown once, when it is created; the server stores only its SHA-256. - An agent can have several keys, each with a name. The list shows each key's name, its first characters, when it was created and when it was last used (never until its first run).
- Deleting a key revokes it: the next request that presents it is refused with
401. - A key belongs to one agent. It runs that agent and reads, aborts and answers the approvals of that agent's API conversations, and opens nothing else on the server. A key of another agent is refused with
404agent_not_found. - Send it as
Authorization: Bearer <key>.
Keyless access
Allow keyless access lets a request without a key run the agent. It is off by default, and a request that presents a key is still checked while it is on. Switching it on asks first, with the warning below; penguin agent api enable --open and set --open print the same warning on stderr once it is on.
[!WARNING] With keyless access on, anything that can reach the server's address can talk to the agent, with the Project's models and credentials. Turn it on only for a server that listens on loopback (
127.0.0.1).
A browser page on another origin cannot use keyless access: the server sends no CORS header on a request without Authorization. See In a browser.
Try it
The API tab ends, for the Project's owner, with Try it: an input holding "What time is it now?" and Run. Run sends one real API run through POST /api/projects/:projectId/agents/:agentId/api/try, your sign-in standing in for a key and the same handler behind it, and shows the stream a program would receive in one output box. The box's header names the run's session_id and switches between two views: Rendered, one numbered row per item or event, with an item's fragments merged into the content they add up to (the answer, a tool call and its arguments, the tool's output), and Raw, one numbered line per data: payload exactly as received. The strip under them gives the run.done status with the Request count, tokens and elapsed time. The default agent can tell the time only by running date, so the example shows a tool call and its result. Running again continues the conversation, as a program does with session_id; New conversation starts another. Stop aborts the run through the Session's abort route, so the stream still ends with run.done, and when the approval mode asks, Allow and Deny appear on the approval.requested row. The conversation is an ordinary API conversation, filed in the Background folder. While the administrator has the Agent API off, Run is disabled.
Call it with curl
curl -N http://localhost:7364/api/amsp/v1/agents/demo/coder/runs \
-H "Authorization: Bearer $ADELIE_AGENT_KEY" -H "Content-Type: application/json" \
-d '{"input":"Summarize README.md"}'
The answer is the run, streamed as it happens: one data: line per event, then data: [DONE]. -N turns off curl's buffering so events print as they arrive. The first event, run.started, names the Session; the last, run.done, says how the run ended and what it counted:
data: {"type":"run.started","at":"2026-10-07T10:00:00.000Z","session_id":"session-2026-10-07-10-00-00-3f9a1c2e","agent":"demo/coder"}
data: {"type":"request.started","at":"…","request":1}
data: {"type":"text.delta","at":"…","role":"assistant","text":"README.md describes"}
…
data: {"type":"run.done","at":"…","status":"completed","requests":1,"usage":{…},"session_usage":{…}}
data: [DONE]
To continue the conversation, send the Session id with the next input:
curl -N http://localhost:7364/api/amsp/v1/agents/demo/coder/runs \
-H "Authorization: Bearer $ADELIE_AGENT_KEY" -H "Content-Type: application/json" \
-d '{"session_id":"session-2026-10-07-10-00-00-3f9a1c2e","input":"Now list its headings"}'
Routes
All paths are relative to the Base URL. A path under it that matches no route is answered 404 not_found in JSON.
| Method | Path | Answer |
|---|---|---|
| GET | /agents/:projectId/:agentId |
{agent: {id, name?, description?}} |
| POST | /agents/:projectId/:agentId/runs |
The run as an event stream; see AMSP |
| GET | /sessions/:sessionId |
{session: {id, agent, status, provider, model_id, created_at, last_active_at}} |
| POST | /sessions/:sessionId/abort |
202 when a run was interrupted, 204 when none was running |
| POST | /sessions/:sessionId/approvals/:toolCallId |
{decision: "allow" | "deny"}; 204, or 404 approval_not_found when it was already answered |
The API tab and penguin agent api manage the settings through /api/projects/:projectId/agents/:agentId/api and its keys routes, signed in as the Project's owner; see Server API.
The run request
interface RunRequest {
session_id?: string; // continue this conversation; omit to start one
input: string | InputItem[];
}
type InputItem =
| { type: "text"; text: string }
| { type: "image_url"; image_url: string }; // a data: URL, or an http(s) URL
inputmust carry a non-empty text or an image.- An image is a
data:URL of an image type, within the 20 MB inline-image cap and the server's attachment total, or anhttp(s)URL, which goes to the model as it is. Files are not accepted. - Without
session_id, the run starts a new conversation andrun.startednames it. With it, the run continues that conversation, which must be an API conversation of the same agent; any other id is404session_not_found.
Conversations
- A new API conversation uses the Project's default model, the server's new-chat sandbox and the agent's API approval mode. Its title is generated from the first input, and its usage and cost count toward the Project, as for any conversation.
- The sidebar lists API conversations in the agent's Background folder, each marked with the API icon. You can open one, read it, answer its approvals and type into it.
- A conversation runs one thing at a time: a run on a conversation that is still working is refused with
409. An agent runs at most four API runs at once; the fifth is refused with429andRetry-After: 2. - Disconnecting aborts the run. To stop a run and still receive how it ended,
POST /sessions/:sessionId/abort: the stream stays open and ends withrun.doneandstatus: "aborted".
Errors
A request refused before the stream starts gets an HTTP status and one envelope, {"error": {"code": "<code>", "message": "<text>"}}:
| Status | code |
When |
|---|---|---|
| 400 | bad_request |
The body is not a JSON object; input is missing or empty; an item has an unknown type; session_id is not a valid id; an image is too large or not an image; decision is not allow or deny |
| 401 | unauthorized |
The agent needs a key and none, or an unknown one, was presented. Checked before the body is read |
| 403 | agent_api_disabled |
The administrator turned the Agent API off |
| 404 | agent_not_found |
No such agent, its API is off, or the key belongs to another agent |
| 404 | session_not_found |
No such Session, it is not an API conversation, or it belongs to another agent |
| 404 | approval_not_found |
The approval was already answered, or never existed |
| 404 | not_found |
No route at this path |
| 409 | task_in_progress, compacting |
The conversation is busy |
| 413 | payload_too_large |
The body exceeds the server's request size cap |
| 415 | unsupported_media_type |
A write without Content-Type: application/json |
| 429 | too_many_runs |
The agent already has four runs going; retry after Retry-After seconds |
| 503 | as the server sends it | The server is shutting down, or the agent or conversation is being deleted |
Once the stream has started, an error is never a separate frame: the run ends with run.done, whose status and error say what happened. See Errors in the stream.
The amsp client
@adelie/amsp is the TypeScript client of the Agent API. It has no dependencies, runs in Node 24 and in current browsers, and exports the AMSP event types.
npm install @adelie/amsp
import { AgentClient } from "@adelie/amsp";
const client = new AgentClient({
baseUrl: "http://localhost:7364/api/amsp/v1",
agent: "demo/coder",
apiKey: process.env.ADELIE_AGENT_KEY,
});
const run = client.run({ input: "Summarize README.md" });
for await (const event of run) {
if (event.type === "text.delta") process.stdout.write(event.text);
}
const first = await run.result();
const second = await client.ask({
sessionId: first.sessionId,
input: "Now list its headings",
onApproval: () => "allow",
});
console.log(second.text, second.usage.total);
client.run()starts the run at once and returns it. Iterate it for the events as they arrive — once; events are kept until read.run.sessionresolves with the Session id as soon asrun.startedarrives.run.result()resolves when the stream ends, withstatus,error,sessionId,text,items,usage,sessionUsageandrequests.textis the main conversation's assistant answers joined with a blank line; a subagent's texts, user messages and compaction summaries stay out of it.itemsholds every event except the.deltafragments, in order.client.ask()runs to the end and returns the same result, keeping nothing for iteration.- Leaving the loop early stops the iteration, not the run: approvals are still answered and
result()still resolves. To stop the run, see Aborting. - An event type the client does not know is passed through, so switch on
event.typewith a default branch.
Approvals
When the approval mode makes a call wait, the run delivers approval.requested and the client answers it for you: with onApproval's decision, or deny when there is no callback or it throws. It answers whether you iterate or only await the result.
import { AgentClient, parseArguments } from "@adelie/amsp";
const result = await client.ask({
input: "Clean up the build output",
onApproval: (request) => {
const args = parseArguments(request.tool_call);
return request.tool_call.name === "exec_command" && args?.command === "ls" ? "allow" : "deny";
},
});
parseArgumentsturns a tool call's arguments, which AMSP carries as the JSON string the model wrote, into an object:{}for none,nullwhen they do not parse to an object.- An approval someone already answered in the Web App is not an error. An answer the server refuses, such as with a key deleted mid-run, ends the run with that
AmspHttpError, closing the connection so the server aborts the run rather than wait for good. client.approve(sessionId, toolCallId, decision)answers one by hand, for a program that reads the stream itself.
Aborting
- Abort the
signalpassed torun()orask()to drop the connection: the server aborts the run, and the run rejects with the signal's reason, anAbortErrorby default. Events not yet read are dropped. run.abort()asks the server to abort and keeps the connection: the stream ends withrun.doneandstatus: "aborted", andresult()resolves with it.client.abort(sessionId)does the same for a conversation by id, and returns whether a run was interrupted.
When a run fails
result()resolves for every run that reachedrun.done, whatever itsstatus; checkstatusanderror.- A refusal before the stream rejects with
AmspHttpError, carryingstatus,codeandmessagefrom the envelope. A body that is not the envelope givescode: "http_error"and a message with the status and the start of the body. - A stream that ends or breaks before
run.done, or carries a block that is not an AMSP event, rejects withAmspStreamError: the run's outcome is unknown, andclient.session(sessionId)tells whether it is still running. - A network failure and an abort reject as
fetchraised them.
In a browser
The same package works in a browser through a bundler. A page on another origin than the server needs a key: the server answers the CORS preflight for any origin, but sends Access-Control-Allow-Origin: * only on a request carrying Authorization. A cross-origin request may carry only Authorization and Content-Type, so extra headers are for same-origin pages and Node.
import { AgentClient } from "@adelie/amsp";
const keyField = document.querySelector<HTMLInputElement>("#key")!;
const client = new AgentClient({
baseUrl: "http://localhost:7364/api/amsp/v1",
agent: "demo/coder",
apiKey: keyField.value,
});
const answer = document.querySelector("#answer")!;
for await (const event of client.run({ input: "What changed today?" })) {
if (event.type === "text.delta") answer.textContent += event.text;
}
[!WARNING] A key in a page is readable by everyone who loads the page. Use a browser client for a tool only you and your team open, with the key entered at run time, or keep the key on a backend that calls the agent for the page.
Client reference
class AgentClient {
constructor(opts: {
baseUrl: string; // ".../api/amsp/v1"
agent: string; // "<projectId>/<agentId>"
apiKey?: string; // omitted = keyless; no environment variable is read
fetch?: typeof fetch; // the global fetch by default
headers?: Record<string, string>;
});
run(opts: RunOptions): Run;
ask(opts: RunOptions): Promise<RunResult>;
agent(): Promise<AgentInfo>;
session(sessionId: string): Promise<SessionInfo>;
abort(sessionId: string): Promise<boolean>;
approve(sessionId: string, toolCallId: string, decision: "allow" | "deny"): Promise<void>;
}
interface RunOptions {
input: string | InputItem[];
sessionId?: string;
signal?: AbortSignal;
onApproval?: (
request: ApprovalRequested,
ctx: { sessionId: string },
) => "allow" | "deny" | Promise<"allow" | "deny">;
}
interface Run extends AsyncIterable<AmspEvent> {
readonly session: Promise<string>;
result(): Promise<RunResult>;
abort(): Promise<void>;
}
interface RunResult {
status: "completed" | "aborted" | "retryable" | "fatal";
error?: { code: string; message: string };
sessionId: string;
text: string;
items: AmspEvent[];
usage: TokenCounts;
sessionUsage: TokenCounts | null;
requests: number;
}
function parseArguments(call: { arguments: string }): Record<string, unknown> | null;
function readSse(body: ReadableStream<Uint8Array>): AsyncGenerator<string>;
class RunCollector {
add(event: AmspEvent): void;
readonly finished: boolean; // run.done has arrived
result(): RunResult; // throws AmspStreamError before run.done
}
class AmspHttpError extends Error { status: number; code: string }
class AmspStreamError extends Error {}
readSse is the client's SSE reader, exported for a program that reads a run's body itself: it yields each event's data, [DONE] included. RunCollector folds the events such a program parses into the RunResult that result() returns.
From the command line
penguin agent api manages an agent's API from a terminal, against the running server, with the same rules as the API tab:
| Command | What it does |
|---|---|
penguin agent api status --agent-id <id> |
Shows whether the API is on, keyless access, the approval mode, the Base URL, the Agent ID, the number of keys and the admin switch |
penguin agent api enable --agent-id <id> [--open | --no-open] [--approve <mode>] |
Turns the API on, optionally setting keyless access and the approval mode |
penguin agent api disable --agent-id <id> |
Turns the API off |
penguin agent api set --agent-id <id> [--open | --no-open] [--approve <mode>] |
Changes keyless access or the approval mode without turning the API on or off |
penguin agent api keys ls --agent-id <id> |
Lists the keys: id, name, first characters, created, last used |
penguin agent api keys create --agent-id <id> --name <name> |
Mints a key. The key alone goes to stdout, everything else to stderr, so $(…) captures just the key |
penguin agent api keys rm <keyId> --agent-id <id> |
Deletes a key |
penguin agent api server on|off |
The admin switch |
Each command also takes --project-id, --server and --json. --approve takes the four modes: allow-all, read-only, always-ask, deny-all. See the CLI Reference.
The commands that change something (enable, disable, set, keys create, keys rm and server) need your sign-in: run penguin auth login once, or penguin auth token on the server's machine. The server refuses them to the local API token, and the CLI then sends them again with that sign-in. Without it they print that hint and exit 1. status and keys ls need none.
The admin switch
Settings › Server › Agent API holds the administrator's Allow the Agent API switch, on by default. Turning it off asks first, then refuses every Agent API request with 403 agent_api_disabled, the CORS preflight excepted. Agents' switches, approval modes and keys are kept, and every member sees the API tab's switch disabled with a note saying why. See Agent API in Settings. The setting is agentApiEnabled in GET/PUT /api/admin/settings, and penguin agent api server on|off sets it from a terminal once you have signed in.