A local-first multi-agent app development platform, built on PenguinHarness
The API path: a program that calls an Adelie Agent
Read this before you write a program that calls an Adelie Agent over the Agent API. The rules in SKILL.md, The API path, hold throughout. The user documentation has every detail: the Agent API guide and the AMSP protocol.
1. Hand the opening to the user
Check first. This command only reads:
penguin agent api status --agent-id <agentId> --json
It prints one line of JSON: agent (the Agent ID), baseUrl, api (enabled, open, approvalMode, keys) and serverEnabled. A key's secret is never in it.
When api.enabled is false, or api.keys is empty and api.open is false, the program cannot run yet. Give the user these steps with the Agent's id filled in. Only the Project's owner can take them.
- Open the Agent's settings and select the API tab (
/agents/<agentId>?tab=api). - Turn on Enable API access.
- Choose the Approval mode for API conversations (see the table below).
- Under Keys, select New key, name it after the program, and copy the key. It is shown once.
- Give the key to the program as the environment variable
ADELIE_AGENT_KEY.
The same steps in the user's own terminal, never in yours:
penguin auth login
penguin agent api enable --agent-id <agentId> --approve <mode>
export ADELIE_AGENT_KEY="$(penguin agent api keys create --agent-id <agentId> --name <program>)"
keys create prints the key alone on stdout, so the variable takes it without showing it. These commands change the Agent's exposure, so they take the user's sign-in: penguin auth login once, or penguin auth token on the server's machine. From your shell the server refuses them with 403 human_required. Never sign in or mint a session to get past that.
When serverEnabled is false, the server's administrator has turned the Agent API off, and every request is refused with 403. Only an administrator turns it back on, in Settings › Server › Agent API.
Suggest the approval mode that fits the program, and say why in one line:
| The program | Mode | What happens |
|---|---|---|
| Has no one to ask: a batch job, a backend | allow-all (the default) |
Every tool call runs, inside the sandbox |
| May let the agent read but nothing more | read-only |
Read-only tools run; every other call waits for the program's answer |
| Shows every tool call to its own user | always-ask |
Every call waits for the program's answer |
| Must never run a tool | deny-all |
Every call is denied; the agent answers without tools |
A call that waits reaches the program as an approval.requested event, and the run waits, with no time limit, for an answer, an abort or a disconnect. The @adelie/amsp client answers it with onApproval, or with deny when there is none. The mode is read when an API conversation is created; a change on the tab applies to conversations created after it.
Leave Allow keyless access off unless the user asks for it. With it on, anything that can reach the server can run the Agent on the Project's models.
To run the program yourself, you need the key in your environment. Ask the user to add it to your key vault as ADELIE_AGENT_KEY: the gear icon on your card on the Agents page, then the key vault tab. Vault values reach your shell on the next task. Until then, the program is unverified.
2. The connection values
| Value | Where it comes from | In the program |
|---|---|---|
| Base URL | Connection on the API tab, or baseUrl from status |
A constant, which ADELIE_AGENT_URL can override |
| Agent ID | Connection on the API tab, or agent from status: <projectId>/<agentId> |
A constant |
| Key | Created by the owner, shown once | process.env.ADELIE_AGENT_KEY, and nowhere else |
- A local server's Base URL is
http://localhost:7364/api/amsp/v1;statusprints the server's real port. Uselocalhost, never127.0.0.1: a local server serves previews on127.0.0.1and answers every API request there with401. - Do not give the program's settings the names the harness sets inside a session:
ADELIE_API_URL,ADELIE_API_TOKEN,ADELIE_PROJECT_ID,ADELIE_AGENT_ID,ADELIE_SESSION_ID. They name the session's own server and Agent, and they override a vault entry of the same name.
3. TypeScript: @adelie/amsp
npm install @adelie/amsp
The client has no dependencies and runs in Node 24 and in current browsers. If your registry does not have the package, call the API over HTTP as in section 4.
import { AgentClient, parseArguments } from "@adelie/amsp";
const apiKey = process.env.ADELIE_AGENT_KEY;
if (!apiKey) throw new Error("Set ADELIE_AGENT_KEY to the key from the agent's API tab.");
const client = new AgentClient({
baseUrl: process.env.ADELIE_AGENT_URL ?? "http://localhost:7364/api/amsp/v1",
agent: "demo/coder", // <projectId>/<agentId>
apiKey, // the client reads no environment variable itself
});
// One question, the whole answer.
const first = await client.ask({ input: "Summarize README.md" });
if (first.status !== "completed") throw new Error(`${first.status}: ${first.error?.message ?? ""}`);
console.log(first.text);
// The same conversation, streamed: pass its Session id back.
const run = client.run({
sessionId: first.sessionId,
input: "Now list its headings",
onApproval: (request) => {
const args = parseArguments(request.tool_call);
return request.tool_call.name === "exec_command" && args?.command === "ls" ? "allow" : "deny";
},
});
for await (const event of run) {
// An event without `origin` is the main conversation's; a subagent's events carry one.
if (event.type === "text.delta" && !event.origin) process.stdout.write(event.text);
}
const second = await run.result();
ask()runs to the end and resolves with the result:status,error,sessionId,text(the main conversation's answer),items,usage,sessionUsageandrequests.run()starts the run and returns it at once: iterate it once for the events, awaitrun.sessionfor the Session id, andrun.result()for the end.- Conversations. Keep one
sessionIdper conversation of the program, such as one per end user or chat thread, and pass it back to continue. Omit it to start a new conversation. Only the Agent's own API conversations can be continued. - Approvals.
onApprovalis called only when the approval mode makes a call wait. Without it, or when it throws, the client answersdeny. A person can answer the same request in the Web App; the first answer counts. - Aborting. Abort the
signalpassed torun()orask()to drop the connection: the server aborts the run.run.abort()asks the server to abort and still delivers the finalrun.done, withstatus: "aborted". - Failures. A refusal before the stream starts rejects with
AmspHttpError(status,code,message; see section 5). After that,result()resolves for every run: checkstatus(completed,aborted,retryableorfatal) anderror. A stream that breaks beforerun.donerejects withAmspStreamError. - Unknown events are passed through. Switch on
event.typewith a default branch. - A web app keeps the key on its own server. The page posts to the app's server, which runs the Agent and relays the
text.deltaevents to the page over SSE, aborting throughsignalwhen the page disconnects: the shape of the RAG recipe'sserver.ts. A key inside a page is readable by everyone who loads the page.
4. Any language: HTTP and curl
BASE="${ADELIE_AGENT_URL:-http://localhost:7364/api/amsp/v1}"
# Start a conversation. The answer streams back as it is produced.
curl -N "$BASE/agents/demo/coder/runs" \
-H "Authorization: Bearer $ADELIE_AGENT_KEY" -H "Content-Type: application/json" \
-d '{"input":"Summarize README.md"}'
# Continue it with the session_id that the first event, run.started, carried.
curl -N "$BASE/agents/demo/coder/runs" \
-H "Authorization: Bearer $ADELIE_AGENT_KEY" -H "Content-Type: application/json" \
-d '{"session_id":"<session_id>","input":"Now list its headings"}'
# Answer an approval.requested event while its run is still streaming.
curl -X POST "$BASE/sessions/<session_id>/approvals/<tool_call_id>" \
-H "Authorization: Bearer $ADELIE_AGENT_KEY" -H "Content-Type: application/json" \
-d '{"decision":"allow"}'
To read the stream in your own code:
- Each event is one
data: <JSON>line followed by a blank line. After the last event comesdata: [DONE]. A line that starts with:is a keep-alive comment, sent after 15 seconds of silence: skip it. - The first event is
run.started, with thesession_id. The last isrun.done, withstatus,errorandusage. The answer is the assistanttext.doneevents without anorigin, or theirtext.deltafragments as they arrive. - Skip every event
typeyou do not know. POST <Base URL>/sessions/<session_id>/abortaborts a run and keeps its stream open untilrun.done.
5. Errors
A request refused before the stream gets an HTTP status and {"error": {"code": "…", "message": "…"}}. Once the stream has started, run.done carries the error instead.
| Status | code |
Usually | What to do |
|---|---|---|---|
| 400 | bad_request |
A malformed body | The message names the field |
| 401 | unauthorized |
No key, a wrong or deleted key, or 127.0.0.1 in the Base URL |
Check ADELIE_AGENT_KEY and that the Base URL uses localhost |
| 403 | agent_api_disabled |
The administrator turned the Agent API off | Ask the user to have an administrator turn it on |
| 404 | agent_not_found |
API access is off, the Agent ID is wrong, or the key belongs to another Agent | Check with penguin agent api status, then ask the owner |
| 404 | session_not_found |
The session_id is not one of this Agent's API conversations |
Start a new conversation |
| 409 | task_in_progress, compacting |
The conversation is still busy | Wait for its run.done: one run per conversation at a time |
| 429 | too_many_runs |
The Agent already has 4 API runs going | Retry after Retry-After seconds |
6. Verify before you hand over
penguin agent api status --agent-id <agentId> --jsonshowsapi.enabledtrue and at least one key.- The key is in your environment:
test -n "$ADELIE_AGENT_KEY" && echo set. Never print the value. - Run the program once with a real input. The run ends with
statuscompleted, and the answer appears. - Tell the user where to find the conversation: the Agent's Background folder in the sidebar, marked with the API icon.
When step 1 or 2 is not done, finish the program anyway, report it as unverified, and end your reply with the owner's steps from section 1. Report the files with relative paths, how to run the program, the Agent ID it calls, the approval mode it expects, and your assumptions.