Run a task with an agent
You can hand a task to an agent. The agent drafts a prompt, you approve it, and the agent does the work. Nothing runs until a person approves it. This page shows you how to plan, start, stop and review an agent run.
Before you start
- Assign the task to an agent. In the task's Agent field, choose the agent. See Manage tasks.
- To plan, run or stop a task, you need to be able to edit the project.
A task assigned to an agent moves through these statuses on its own:
| Status | What it means |
|---|---|
| Not Started | No prompt yet. |
| Planned | The agent has drafted a prompt for you to review. |
| In Progress | The agent is running. |
| Awaiting Review | The run finished and the result is ready for you. |
| Complete | You accepted the result. |
Plan the task
- Open the task. From the task list, you can select Plan in the Actions column.
- In the Prompt card, read Press Plan to draft a prompt for followed by the agent's name.
- Select Plan.
The agent drafts the prompt, and the task moves to Planned. The card shows Generated and the time the prompt was drafted.
Review and edit the prompt
- Read the prompt in the Prompt card.
- Edit the text if you need to. Run uses the exact text shown.
- To ask for a fresh draft, select Re-plan. If you've edited the prompt, your browser asks Replace your current prompt with a new plan? Your edits will be lost. Confirm to replace it, or cancel to keep your edits.
The card reminds you: The Agent will not start until a Human presses Run.
Start the run
- Select Run. After a successful run, this button reads Re-run.
The task moves to In Progress. The Prompt card shows the Approved prompt, which you can't edit while the agent works, and the line: the agent's name followed by is working on the approved prompt. In Progress.
Follow the run
While the agent works, the card shows Running for and how long the run has taken, followed by started and the start time. The time is shown as a rounded duration, such as 42 sec, 5 min or 1 hr 30 min, and the page updates on its own every few seconds.
Stop a run
- Select Stop.
- Read the Stop this Agent run? dialog. The agent keeps the approved prompt, and the task returns to Planned. Nothing this attempt produced is kept.
- Select Stop run to confirm, or Cancel to let it carry on.
The card then shows Stop requested and the time you asked. Stopping may take a moment.
Review the result
When a run succeeds, the task moves to Awaiting Review. The Result card shows the agent's result, the agent's name and the time it finished.
- Read the result.
- To accept it, select Complete. The task moves to Complete, and the prompt can no longer be edited.
- To try again instead, edit the prompt and select Re-run, or select Re-plan for a new draft.
If there's no result yet, the card reads No result yet. A result from an earlier run shows under Previous result.
See the run history
The Audit trail card lists every run of the task, newest first. Each entry shows:
- Who approved it (Approved by and a name, or Run approved).
- The agent's name.
- The outcome: Running, Succeeded, Failed or Stopped.
- When the run was approved.
The newest entry is open. Select any entry to show or hide its activity, a timed list of what the agent did. Before the first run, the card reads No runs yet.
Troubleshooting
- The assigned Agent is unavailable. The agent can't run right now, so Plan and Run are greyed out. Choose another agent, or ask an administrator to make the agent available.
- Add a prompt before pressing Run. The prompt is empty. Select Plan, or type a prompt.
- Your edits would be replaced. Press Plan again to confirm. Select Re-plan again to replace your edited prompt.
- Plan could not be created. Try again in a moment. or Run could not be started. Try again in a moment. Wait a moment and try again.
- That Agent run already finished, so there was nothing to stop. The run ended before your stop reached it. Review the result.
- The run could not be stopped. Try again in a moment. Select Stop again after a short wait.
- There is no readable Result to accept yet. Wait for the run to finish before you select Complete.