Agents on human tasks

An AI agent can work through a person's Orchestra inbox. To Orchestra it is one more caller: it lists tasks, reads them, claims and completes them through four tools of the Orchestra Tool submodule (see Tool API), with an account's own access and the same checks as that person's pages. Orchestra does not tell an agent from anybody else.

An example

A leave request goes to the employee's manager, Alice, as a comment task: the outcomes are approved and rejected, and a rejection needs a comment.

Alice gets an assistant: an account of its own, alice-assistant, with the Process Orchestra tasks permission, as anybody working tasks has, and the Access Orchestra tools permission, which lets an AI agent use it through the Tool AI Connector or an MCP client. Alice gives it cover on her delegations page (Delegation). The assistant then lists her tasks as its own:

{
  "handle": "orchestra-task:42",
  "label": "Review the leave request",
  "workflow_id": "leave_request",
  "instance_id": "17",
  "instance_label": "Leave request from Bob",
  "created": 1793700000,
  "outcomes": [
    {"outcome": "approved", "label": "Approve", "api": true,
     "payload": [{"name": "comment", "data_type": "string", "label": "Comment",
                  "description": "", "required": false}]},
    {"outcome": "rejected", "label": "Reject", "api": true,
     "payload": [{"name": "comment", "data_type": "string", "label": "Comment",
                  "description": "", "required": true}]}
  ]
}

It reads the task, whose description says what is asked: "Leave for 3 days." It finds the dates overlap a colleague's leave, and rejects the request with the comment the outcome needs:

drush tool:run orchestra_complete_task --uid=7 \
  --input='{"handle":"orchestra-task:42","outcome":"rejected","payload":{"comment":"It overlaps a colleague."}}'

The task records the assistant as its completer, on Alice's behalf, as for anybody covering for her. The step's payload variable holds {"outcome": "rejected", "comment": "It overlaps a colleague."}, as when Alice rejects it on the task's page, so the flows route on it the same way.

The tools

Tool	What it does
orchestra_list_my_tasks	Lists the caller's open tasks, newest first, those of the people it covers included, with their outcomes: whether the caller may choose each (api), and what its payload carries (payload). A page at a time.
orchestra_get_task	Reads a task as its page shows it: its title, its description, its messages and its outcomes, described as in the list.
orchestra_claim_task	Claims a task offered to a pool the caller, or a person it covers, belongs to.
orchestra_complete_task	Completes a task with an outcome and its payload, such as a comment. It cannot be undone.

They need the Access Orchestra tools permission, the gate of every tool (Permissions), the Process Orchestra tasks permission every task needs, and the caller's own access: a tool acts on a task only where the account could. A pull-based operation is not listed, since it is not a task of the inbox.

orchestra_list_my_work_items lists both: the caller's tasks and the operations they pull, as their My actions page shows them. Each says its mode, task or operation. One whose handle is null cannot be acted on through the tools, and is acted on through its page. Like that page, it needs no permission beyond the gate.

What an agent may decide

Who may act on a task is the usual question, answered the usual way: the task's assignment, and the cover its person gives. An agent with its own account decides what that cover lets it decide, and its decisions are recorded as its own, on the person's behalf. To keep a person deciding, give the agent no cover over those tasks, or no permission to use the tools.

An agent's decision is as good as what it reads, and a task's description may carry text that somebody else typed. Let an agent complete only the tasks where a wrong decision is cheap to undo, or caught by a later step.

What each outcome is completed with

Each outcome in the task list says what it is completed with (Outcome settings):

• api: whether the caller may choose it. The step's author ticks No API on an outcome a person must choose on the task's own screen, such as one whose work is a webform to fill in, a payment or a content form. It is listed with api: false, and completing the task with it is refused: leave it to a person.
• payload: what its payload carries beside the outcome, described as typed data, the way a Tool API tool describes its inputs: a name, a data type such as string, a label, a description and whether it must be given. A comment task's outcomes take a comment, required on its comment-requiring ones. A comment interaction takes one the same way. A plain user task and a message take nothing beyond the outcome: "Get an Orchestra task" returns the message's text among the task's messages. A payload that is null is not described by the step's type: send the outcome alone.

A task without outcomes lists one outcome, '', labeled Complete, to complete it with. A completion that misses a required entry, gives one the outcome does not take or one that is not valid, is refused with the reason, and the task stays open. So is an outcome listed with api: false.

On a client site

On a site running Orchestra Client, the tools reach the remote Orchestra through its HTTP API: the tasks, task/claim and step/resume endpoints (see the OpenAPI document). The client names the account running the tool by an identity proof, so the remote Orchestra lists and acts on that account's tasks. An agent has no browser, so no presence key: the proof is the client site's word (asserted), which works only where the remote granted that scheme to the site, and rests on the remote trusting it.