Background agents

Some requests take longer than a reply: reading a long history, checking many records, drafting a long document. In a workstream, Harmony Agent can hand that work to a background agent and keep talking with you while it runs. The background agent works as you, with your connectors, and posts its result in the chat when it is done.

How this fits in Harmony

flowchart LR
  A[You ask in a workstream] --> B[Harmony Agent starts a background agent]
  B --> C[Background agents tray]
  C --> D[Steer or stop it]
  C --> E[Result in the chat]
  E --> F[Your verdict]

A background agent is Harmony Agent doing one job in a run of its own, while your chat with Harmony Agent stays free. Only you see it: its row in the tray, its work and its result are private to the person who started it, until you share the result.

Where background agents run

On Harmony's models, background agents come with Pro, Scale and Enterprise seats. On your own model key they run on every plan.

Step-by-step

1. Start a background agent

1. In a workstream, ask Harmony Agent for the work, with @Agent in the chat or in the agents panel.
2. Harmony Agent decides whether the work suits a background agent. Long work that you don't need before you carry on usually does. Work that splits into separate parts can get one background agent per part, up to three at once.
3. You can also ask for it, for example @Agent do this in the background.

Harmony Agent replies that the background agent is running and ends its reply. The Background agents strip appears at the bottom of the agents panel, with a spinner and a count such as 1 running.

If Harmony Agent can't start one, it tells you why. For example, when three are already running in the workstream: This workstream already has 3 background agents running, which is the most it can run at once. Wait for one to finish or stop one, then try again.

2. Find it in the tray

The tray is part of the agents panel, so open the panel to see it.

• Agents panel at its usual size. The tray is a strip along the bottom of the panel. It starts folded; choose Background agents to open the list.
• Agents panel maximized (Maximize agents panel). The tray is a card attached to the top of the chat box. It starts open.

The header counts what is in the tray, for example 1 running · 1 starting · 1 finished. Each row shows:

3. Watch its work

1. Choose a row to open it. One row opens at a time.
2. Read the two meters: Step (for example 8 of 20) and Spend (what it has spent of its spending limit). The spend bar changes to the warning colour at 90%.
3. Read its work below the meters, as it happens: each step, the tools it uses and its reply as it writes it, in the same view as any chat with Harmony Agent.

Before its first step, the box says It starts as soon as a worker picks it up., then Its first steps show here as it works.

4. Steer it

1. Open the row.
2. Type in the box under its work (it reads Steer followed by the job's name).
3. Press Enter or choose Steer.

The row confirms Sent. It reads your message at its next step. The background agent gets your message with the result of the step it is on, and follows it.

5. Keep talking to Harmony Agent

Your chat with Harmony Agent stays free while background agents run. If you send a message while Harmony Agent is still writing a reply, Harmony decides where the message goes and shows a note under it:

6. Approve what it writes

A background agent asks before it creates, changes or sends anything in a connected system, the same as Harmony Agent does. The request appears in the agents panel under the reply that started it: Background agent job name needs your approval to continue., with the approval card. The agent waits for your answer. Its time limit keeps running while it waits. See Approving what agents write.

7. Stop it

• One background agent: choose the square stop button on its row (its tooltip reads Stop followed by the job's name). While Harmony Agent is writing a reply, a message asking to stop a background agent stops it too (see step 5).
• The reply Harmony Agent is writing: choose Stop response. This stops the reply and every message waiting to be answered after it. Background agents keep running: stop each one from its row.

A stopped background agent posts what it had found so far:

Background agent stopped: At-risk Q4 renewals.

What it had so far:

Its row shows Stopped and Stopped before it finished. You aren't charged for it.

8. Get the result

When a background agent finishes, Harmony:

1. Posts its result as a reply under the Harmony Agent reply that started it. In the agents panel the result reads in the conversation, under that reply. Only you see it.
2. Marks its row Done with the start of the result as its status line. The row stays for about 8 seconds, longer while it is open, then folds away. Choose the X (Dismiss) to remove it sooner.
3. Sends you a notification: Background agent finished: followed by the job's name.

To jump to the result, choose View result on its row. If the job came from another chat in the workstream, Harmony switches to that chat.

To share the result with the workstream, hover over it and choose Collaborate.

If you asked Harmony Agent to do something with the result when it finished, such as chart it when it's done, Harmony Agent does that in a new reply in the same chat. On your next message, Harmony Agent also knows the result, so you can ask about it straight away.

9. Judge the result

Mark the result Useful or Not useful with the thumbs on its row in the tray or under the result in the agents panel. Only the person who started a background agent can see and judge its result, so your verdict is the outcome. See Judging work and the useful rate.

Limits

Each background agent has three limits, set when it starts.

Each note is followed by What it had so far: and what it had found, when it found anything. Its row shows Hit its step limit, Hit its budget or Timed out.

There are also limits on how many run at once: three in a workstream, and three for one person across all workstreams. When you already have three: You already have 3 background agents running, which is the most one person can run at once. Wait for one to finish or stop one, then try again.

What it costs

On Harmony's models, a background agent counts against your 5-hour and weekly limits. On your own model key, the provider bills it.

• Before it starts, Harmony quotes it from what your recent background agents cost. If the quote won't fit what is left of your limits, Harmony Agent doesn't start it and tells you, for example I can't start this: you've reached your five-hour limit. You can wait for it to reset, use extra usage, or switch to your own model key. Nothing has been charged.
• When it finishes, the charge shows beside the thumbs on its row and under its result, as a share of your limit (for example 2% of 5h) or as money on your own key (for example $0.41 · OpenAI key).
• What is charged: a background agent that finishes, or that reaches its step or spending limit, is charged for the work it did. One that you stop, that runs out of time or that fails isn't charged.

See Quotes and charges and Usage limits.

If Harmony restarts while it runs

A background agent doesn't start over. Harmony picks it up again and it carries on from the step it had reached, with its steps, spend and time so far, and with any messages you sent it. While it is picked up, its row briefly shows a hollow circle in place of the spinner.

Harmony does this up to twice for one background agent. After that, it posts Background agent did not finish: job name — Harmony restarted while it was running and it couldn't resume., with what it had so far. Its row shows Interrupted, with Harmony restarted and could not pick it up again under it, and you aren't charged.

When something goes wrong

If a background agent can't finish, its row shows Failed with the reason as its status line, and it posts a note in place of a result, for example:

• Background agent did not finish: job name — it hit an error.
• Background agent did not finish: job name — its run ended before it wrote an answer.
• Background agent did not finish: job name — it finished without writing an answer.

The note includes What it had so far: when it had found anything. You get a notification that names what happened, followed by the job's name: Background agent failed:, Background agent ran out of time:, Background agent reached its spending limit:, Background agent reached its step limit: or Background agent was interrupted by a restart:. A failed background agent isn't charged. To try again, ask Harmony Agent.

In Runs

Each background agent's work is recorded as a run of its own, with its task, what it did and how it ended. See Runs.

Background agents on tasks {#on-tasks}

When you put Harmony Agent on a task, it works as a background agent for you, but everything lands on the task instead of in a chat: its progress, its approval requests, and its result as a task comment everyone on the task can read. It doesn't appear in the tray. Stop it with Stop on its card, and steer it by commenting on the task. See Agents on tasks.

Example scenario

Priya Shah runs the Q4 launch workstream. On Monday morning they type @Agent compare every Q4 launch customer's renewal date with their open support tickets and list the ones at risk.

1. Harmony Agent replies that it has started a background agent, At-risk Q4 renewals. The strip at the bottom of the agents panel shows 1 running.
2. Priya asks Harmony Agent a quick question about the launch date and gets an answer straight away.
3. Priya opens the tray and sees the agent on Step 6 of 20, reading support tickets. They type Only EMEA customers and choose Steer. The agent narrows its search at its next step.
4. While Harmony Agent is answering another question, Priya types for the renewals check, skip customers on annual plans. The note under it reads Sent to At-risk Q4 renewals.
5. Twelve minutes later Priya gets a notification: Background agent finished: At-risk Q4 renewals. They choose View result, read the list of seven customers, and mark it Useful. The charge beside the thumbs reads 2% of 5h.
6. Priya chooses Collaborate on the result so Sam Okafor, who owns renewals, can see it in the workstream.

FAQs

Can I close the agents panel or the app while it runs? Yes. It runs on Harmony, not on your device. When it finishes, the result is in the chat and you get a notification.

Can my teammates see my background agents? No. The tray, the agent's work and its result are private to you. Choose Collaborate on the result to share it.

Why can't I start one in a room or a direct message? Background agents belong to a workstream: they run in its context and post their result in its chat. In a room, Commons or a direct message, Harmony Agent does the work in its reply.

Does Harmony Agent know what my background agents found? Yes. On your next message in that chat, Harmony Agent sees the results of background agents that have finished and which ones are still running, so it doesn't start the same work again.

Can a background agent start more background agents? No. It does all its work itself.

Can it change things in my connected systems without asking? No. It asks you first, the same as Harmony Agent. See Approving what agents write.

Why does a row say "It has already finished." when I steer it? It finished, or was stopped, before your message arrived. Read its result, or ask Harmony Agent to carry on from it.

Where did the row go? A finished row folds away about 8 seconds after it ends, unless it is open. The result stays in the chat.

What does Stop response stop? The reply Harmony Agent is writing and the messages waiting to be answered after it. Background agents keep running; stop each one from its row.