Languid/docs/approvals

Using Languid · Approvals for apps

Approvals for apps

Your own app can run your agents through Languid's XRPC API and answer the calls they ask you about, the way the web chat does. This page covers starting a run that asks, showing what's waiting, and answering it.

How approvals work

Some calls need your yes before they run: bash, edit and write on a computer, record writes from a script that your agent's policy says to ask about, and sharing error reports. Your rules for a computer decide first. A call they allow runs without asking, and a call they deny is refused without asking.

When a run asks, Languid writes an ai.languid.approval.request record in the agent's space. Your answer is an ai.languid.tool.approval record, written under the request's own record key, so a request has one answer at most. See Records.

A tool call that's waiting survives a restart of the service. After a restart, the question comes back under a new run. A script that asks partway through doesn't survive one: the script stops, and its call ends as interrupted.

Sign in

Sign people in with atproto OAuth and call Languid through their PDS. Ask for an rpc scope for each method you call, with Languid as the audience:

rpc:ai.languid.agent.run?aud=did:web:languid.ai%23languid
rpc:ai.languid.agent.getRun?aud=did:web:languid.ai%23languid
rpc:ai.languid.approval.list?aud=did:web:languid.ai%23languid
rpc:ai.languid.approval.answer?aud=did:web:languid.ai%23languid

Send each call to the person's PDS with this header:

atproto-proxy: did:web:languid.ai#languid

Their PDS forwards the call to Languid with a token for that one call. Apps can call only these four methods, and only on that person's own agents: any other agent's name gets 404 AgentNotFound.

Scripts you run yourself can send Authorization: Bearer with the token from languid login instead:

jq -r .server.token ~/.languid/state.json

Start a run that asks

POST /xrpc/ai.languid.agent.run
{ "agent": "scout", "prompt": "Tidy the notes folder", "thread": "3n2js7khmj2aq", "approval": "ask" }

The response is { run, thread, accepted, since, message }. With accepted: "queued", the thread already had a run: follow that one from since.

approval sets what happens to calls that need your yes:

approvalCalls that need your yes
"ask"wait for your answer
"allow"run without asking (not sharing error reports, which always asks)
"auto"are approved when a classifier model finds them reversible and covered by the owner's latest message, and wait for your answer otherwise (see Auto)
"deny"are refused with "no one was asked: this run was started with changes denied"

Without approval, approveWrites: true means "allow", and anything else means "deny". If you send both, approval wins. A message sent into a thread that already has a run goes by that run's mode.

The other fields are optional: thread (or continue: true for the latest thread; leave both out for a new thread), computer, via (your app's name), and clientMessageId (send it again and the message isn't recorded twice).

Attach images with images: [{ data, mimeType }], where data is base64 (without a data-URL prefix). Send up to four PNG, JPEG, GIF or WebP images, each at most 5 MB. prompt may be empty for an image-only message. Images are saved as private blobs; authenticated agent.getContext returns hydrated image parts for history, including after a service restart.

Follow the run

GET /xrpc/ai.languid.agent.getRun?run=<run>&since=<next>

This returns { run, thread, status, events, next, … }. status is running, done or error. Poll with since set to the last next. Two events matter here:

{ "seq": 4, "type": "approval", "id": "toolu_01…", "tool": "bash", "arguments": "{\"call_intention\":\"Delete old drafts\",\"command\":\"rm drafts/*.md\"}", "computer": "laptop", "always": { "command": "rm" }, "request": "at://did:plc:…/ai.languid.approval.request/3n2mivd4nlscu" }
{ "seq": 5, "type": "decision", "id": "toolu_01…", "approved": true }

List what's waiting

When your page loads, list what's waiting rather than replaying old events:

GET /xrpc/ai.languid.approval.list?agent=scout&thread=3n2js7khmj2aq

thread is optional. The response lists open requests that something still waits on, newest first:

{ "approvals": [{
  "uri": "at://did:plc:…/ai.languid.approval.request/3n2mivd4nlscu",
  "cid": "bafyrei…",
  "thread": "3n2js7khmj2aq",
  "call": { "uri": "at://…/ai.languid.tool.call/3n2mivcwwy2cu", "cid": "bafyrei…" },
  "tool": "bash",
  "arguments": "{\"call_intention\":\"Delete old drafts\",\"command\":\"rm drafts/*.md\"}",
  "intention": "Delete old drafts",
  "computer": "laptop",
  "always": { "command": "rm" },
  "expiresAt": "2026-11-18T21:35:00.000Z",
  "createdAt": "2026-11-18T21:30:00.000Z",
  "run": "a04b7288-9a98-43e5-927d-37e65d054fa0"
}] }

intention, computer and always are present only when they apply. A script's write also has n (which of the script's asks it is) and method. Follow run with getRun to see what happens after you answer.

Answer

POST /xrpc/ai.languid.approval.answer
{ "agent": "scout", "request": "at://did:plc:…/ai.languid.approval.request/3n2mivd4nlscu", "approved": true, "via": "my-app" }

The response is {}, or { "rule": { "computer", "tool", "command"? } } when you sent always: true.

Always allow

Offer it only when the request has always. always: true approves the call and saves a rule for that computer:

The rule also approves any other call in the same run that is waiting and that the rule now covers. A script's record writes have no always: which writes need no asking is set on the agent's settings page, under Record writes.

A page that answers

  1. Start runs with approval: "ask".
  2. On load, call approval.list for the thread. While a run goes on, add a card for each approval event, and remove it on the matching decision.
  3. On each card, show the intention as the heading, then the tool, the computer and the command (or the record being written).
  4. Offer Allow and Deny, plus Always allow when always is present (for example "Always allow rm on laptop"). Show the time left until expiresAt.
  5. Answer from your server, so the token stays there. On a 409, drop the card.

Next: Speech and models APIThis page as Markdown