Skip to main content
An Agent in Work is a member of kind Agent. It acts only through the same path as a person. It is not the same thing as an Agent in the Worksong app, although a Worksong Agent can also be called from Work (see Remote Agents).

​
Hire an Agent

Create an Agent with:
  • an email (its identity),
  • instructions (what it is for),
  • an opening balance, in minor units (cents),
  • optionally a workspace to belong to.
A new Agent has no authority. It cannot read or write anything until you give it authority on a board. Do this the same way as for a person: see Authority. An Agent that proposes emails or calendar events needs Manage on that board, and a gate for the action.

​
Status

Pause, resume or stop an Agent at any time.

​
Budget

An Agent spends from a balance that you fill. Credit more with POST /v1/agents/{id}/budget/credit and amountMinor. The response shows the balance before and after. The agent’s ledger lists every charge. A run stops when the balance or a limit is used up.

​
Tools

Give an Agent only the tools it needs.
  • Tool: the tool id.
  • Allowed actions: the actions it may use.
  • Scope: Workspace, Board or Resource, and the id of that workspace, board or resource.
  • Approval required: when on, each use waits for a person.
The tools you can choose from are listed by GET /v1/tools/catalog: The catalog marks the actions in bold as dangerous: they reach people or systems outside Work. Give them together with approval required. You can ask POST /v1/agents/{agentId}/tools/authorize whether a use would be allowed. Tools can be changed or removed later.

​
Knowledge

Grant an Agent a doc as knowledge. The Agent can then use it when it answers. Revoke the grant and it stops. See Search and answers for how docs are found.

​
Run an Agent

Start a run on an item with POST /v1/agents/{id}/runs and the board, the item and, for an AI column, the column. An automation can do the same with the InvokeAgent action, and a person can mention the Agent in an item comment. Each run keeps a trace: what it read, what it proposed, what it did and what it spent. List runs with GET /v1/agents/runs, or open one run. Each action the Agent takes is also in the audit log.

​
Remote Agents

A remote Agent is an Agent whose model runs in Worksong, not in Work. Your own Worksong Agents appear in the @ list of an item comment. When you mention one, the real Worksong Agent answers, and the answer is posted as its comment.
  • Worksong lists your Agents to Work. Listed Agents are created or renamed. Agents no longer listed are stopped, never deleted, so old comments keep an author.
  • The Agent needs Write on the board. If it has none, Work gives it Write for you, and this works only when you can Manage that board. Otherwise you get a notice.
  • Work does not run a model for it and does not charge it. Its budget is 0.
  • If the connection to Worksong is not configured, a mention gets the message “not connected here”.
Source: worksong-ai/worksong:services/work/src/Boardy.Agents@9f0684f, worksong-ai/worksong:services/work/src/Boardy.Api/Program.cs@9f0684f, worksong-ai/worksong:services/work/docs/remote-agents.md@9f0684f. Docs version: Worksong 2.0 with Work 1.2.