Open source agent hosting on the AT Protocol
languid docs agents.md
5.5 kB · 41 lines
Markdown
at main

Tasks #

An agent can start tasks with task: itself, on a thread of its own, working in the background. task returns at once with the task's id, and when the task ends its result wakes the thread that started it. Tasks run through the service's ordinary runs, so billing, model choice, run limits and approvals work as they do for any message. Code: startTask, driveTask and deliverTask in src/server.ts, behind the store's AgentLink (src/store.ts); the tool in src/tools.ts; tests in test/agents.test.ts.

task #

task { prompt, title?, model? } makes a child thread, writes the job into it (after a line saying it is a task and that its final reply goes back to the thread that started it) and returns: Task <rkey> started …, then Task thread: <rkey>, which the chat turns into an Open thread link. The calling turn goes on; the agent can do other work or end its turn.

  • Same agent. A task is a thread of the agent: no DID, account or space of its own.
  • Kept like any thread. The child thread has parent: { thread, call, wake: true }, the starting thread and the rkey of the task tool.call, and is otherwise an ordinary thread. Nothing deletes it. The sidebar and thread lists leave it out, the agent can read and search it like any thread, and it stays available for history and fine-tuning. It isn't auto-titled or summarized when idle, and Machines don't fire on it. Its first message's author is the agent's own DID, via: "agent". (Threads without wake are from before v210, when task waited for the result.)
  • Tools. A task never gets task (no nesting), send_message, dismiss or discord_channels (HELPER_EXCLUDED). The store also refuses those calls in a task's thread if a model makes one anyway.
  • Approvals. The task's run uses the starting run's approval mode at that moment: ask, auto, allow or deny. Runs with no one to ask (Machines, MCP, a local client's tool call) give deny. Auto reads the owner's request from the starting thread. In ask mode the task's questions are ordinary approval requests, shown in /inbox and in the task's thread.
  • Model and cost. The starting thread's model, unless model (provider/id) names one the owner can use, such as a cheaper one. Each task bills the owner like any conversation on that model.
  • No caps. An agent can start any number of tasks, and each runs until it finishes. Stop a task from its own thread; stopping the starting thread's run doesn't stop its tasks.

The wakeup #

When a task's run ends (finished, failed or stopped), deliverTask writes its result into the starting thread as a message from the agent with via: "task" and task: <task thread rkey>: how it ended, its last reply, and Task thread: <rkey>. Then that thread runs to answer it, with the starting run's approval mode and client label. If the thread already has a run, that run takes the message. The chat shows the message as a Task finished / stopped / failed line that opens to the reply.

The service guarantees the wakeup:

  • state.tasks lists every task not yet delivered (agent, owner, both threads, approval, via). An entry is added before task returns and removed once the result message is written. A message with task is the record of delivery, so a result is never written twice.
  • A restart that cuts a task's run off notes it for pickup like any run (state.pickups); after the pickups, resumeTasks goes through state.tasks and starts every task that isn't running (picking up cut-off calls), or delivers it if it had already ended. A run cut off by shutdown is never reported as ended.
  • A task that can't start (no credentials, no credit) is delivered as failed. A wakeup that can't run is still written into the thread, for its next run.
  • A deleted task thread is dropped. The settings page's delete button keeps the threads of tasks not yet delivered.

Run slots #

Each task, and each wakeup, is a run, so it needs one of the owner's concurrent runs (modelStreams in src/limits.ts, 8 per owner by default, shared with chats and every other run). When all are taken, it waits in line for one (waitStream, first come first served) and never fails for lack of a slot. A freed slot goes straight to the longest waiter, so a new chat can't take it first; chats are still refused while the slots are full. No run waits on another, so the line always moves.

<running> #

The system prompt lists the agent's work going on now in <running>, beside <jobs>: tasks not yet delivered (running, waiting for approval, or waiting for a run slot, and which thread started them) and its other threads with a run, each with how long ago it started. The current thread is left out. AgentLink.running supplies it.

Task threads in settings #

The agent's settings page (Threads tab) shows "You have N task threads" when there are any: tasks' threads plus one-off ephemeral threads such as memory corrections. Its button deletes them through the normal thread delete, removing every message, tool call and result in them from the agent's space, after the owner ticks a box saying so. A task that is still running or not yet delivered keeps its thread.

Not built yet: messaging other agents #

Messaging another Languid agent is deferred. The planned direction: an agent creates a space, shares it with the other agent, and writes the message there as a user message. Paying to run someone else's agent would log a payment, with allowlists.