When an agent works for more than a moment, silence becomes a product decision.
Silence can make users wonder whether anything is happening, whether the task has failed, whether it is safe to send a correction, or whether an irreversible step is about to occur. The obvious response is to stream activity: every tool call, every thought fragment, every subtask, every piece of intermediate text.
That is not progress. It is noise.
Progress is a claim about the state of work. A good progress update tells the user what is true now, what changed, what happens next, and when they can meaningfully intervene. A bad update overstates certainty, exposes irrelevant internal detail, or creates the illusion that a task is complete because the agent wrote something confident.
A progress update is a user-control interface: it should make the next safe decision easier, not merely prove that the system is busy.
The A2A Protocol 1.0 specification offers a useful interoperability perspective. A Task has optional artifacts and a status object containing a required lifecycle state plus optional message and timestamp. That structure is valuable even outside the protocol: state is not the same thing as prose, and an artifact is not the same thing as a status message.
OpenAI's model guidance reaches a complementary conclusion for agent experiences: preambles can improve usability by giving an initial useful status update and making tool use easier to follow. Preferring updates at meaningful state transitions over routine tool-by-tool narration is this article's proposed product principle. The Responses API reference separately documents background responses with lifecycle status, illustrating why a long-running operation's state should remain distinct from its final message.
Together, these ideas suggest a product principle: agents need intermediate updates, but those updates need a contract.
Why activity streams fail users
An activity stream can contain many true facts and still fail to help:
- “Calling search tool” does not tell the user whether the agent found relevant evidence.
- “Analyzing files” does not say which task boundary the analysis serves.
- “Almost done” is not an operational state and often has no reliable meaning.
- “Completed” may be false if a required validation, approval, or follow-up is still pending.
- A raw trace can expose private names, sensitive context, or implementation detail that a user did not need.
The opposite failure is a polished but vague commentary message. An agent says, “I’m on it,” then disappears for several minutes. The user cannot tell whether they should wait, correct the objective, or start another task.
The right middle ground is not a more verbose status feed. It is a small set of updates that correspond to meaningful changes in the task's decision surface.
The Agent Progress Contract
The Agent Progress Contract is a proposed six-part structure for user-visible updates. It can be expressed as a concise sentence, a task card, or a richer UI. The contract matters more than the presentation.
- Element: Task identity and phase — What it answers: Which work is this update about, and what stage is it in? — Example of the useful content: The requested task and a broad phase such as understanding, investigating, implementing, validating, waiting, or complete
- Element: Truthful current state — What it answers: What is known to be true now? — Example of the useful content: Working, queued, blocked, awaiting input, awaiting verification, completed, failed, or cancelled—without pretending uncertainty is success
- Element: Concrete outcome — What it answers: What changed since the last meaningful update? — Example of the useful content: A source was verified, a blocker was identified, a draft was created, a test result was observed, or no new evidence was found
- Element: Next safe boundary — What it answers: What is the next decision point or verification step? — Example of the useful content: The agent will compare sources, validate a change, wait for an approval, or report a specific limitation
- Element: User intervention — What it answers: When can the user steer, clarify, approve, defer, or cancel without creating ambiguity? — Example of the useful content: A clear invitation only when a user choice materially changes scope, priority, authority, or the intended outcome
- Element: Safe visibility — What it answers: What may be shown in this audience and what must stay out of the update? — Example of the useful content: A user-appropriate summary with no private data, credentials, raw internal reasoning, or security-sensitive operational detail
The contract does not require a continuous “percentage complete.” Many agent tasks are research, debugging, or planning problems whose remaining work cannot be measured honestly. A phase and a next safe boundary are often more useful than a fabricated progress bar.
Report outcomes, not internal monologue
An agent's internal reasoning is not a suitable status interface. It can be incomplete, speculative, sensitive, or confusing when viewed out of context. Even a detailed tool trace may be more noise than signal.
The user-visible update should therefore be an outcome-oriented statement:
- “I confirmed the current task has three independent research gaps; I’m checking primary sources before drafting.”
- “The first validation passed, but the next step depends on reconciling two conflicting results.”
- “The work is waiting because the next effect requires a user decision; no change has been made.”
- “The task finished its research phase and is moving to a reviewable draft; no external action is planned.”
These updates reveal a meaningful change without exposing hidden chain of thought or raw operational data. They also make the agent easier to steer. A user who learns the task is in a research phase can correct the scope before the agent spends time drafting. A user who learns an effect is awaiting approval can decide whether to authorize or change direction.
Design updates around state transitions
The most useful updates occur when the task changes state or reaches a decision boundary:
- Event: Work begins — Useful update behavior: Acknowledge the goal and name the first high-level step
- Event: New evidence changes the plan — Useful update behavior: State the concrete finding and the updated next boundary
- Event: Work becomes blocked — Useful update behavior: Name the blocker in user-safe language and explain what would unblock it
- Event: A user decision is required — Useful update behavior: Present the smallest decision that changes the next action, without disguising it as a routine status
- Event: A meaningful phase completes — Useful update behavior: State what is now available, what remains, and whether anything was changed externally
- Event: Work ends — Useful update behavior: Make the terminal state explicit: complete, partially complete, deferred, failed, cancelled, or awaiting follow-up
This is why a progress contract is distinct from an event feed. An event feed preserves what happened. The contract determines which state changes are worth presenting as user-facing control points.
It is also distinct from input-delivery semantics. Queueing, steering, and interruption determine how a new user message reaches ongoing work. A progress update determines whether the user can recognize that a message would matter right now.
Avoid false completion
The most damaging progress mistake is a premature terminal claim.
An agent can complete a subtask without completing the user's objective. It can finish a tool call without verifying its result. It can produce a draft without receiving required review. It can stop because a limit was reached without having resolved the original problem.
Progress updates should keep those states separate:
- Completed: the declared success condition was met and the result is available.
- Partially completed: a bounded portion is ready, while named work remains.
- Awaiting verification: an action or result exists but has not yet satisfied its verification condition.
- Blocked: a dependency, approval, or required input is missing.
- Deferred: the task remains valid but is intentionally not progressing now.
- Failed or cancelled: work stopped, with an honest account of what remains or what may need reconciliation.
These terms are not bureaucracy. They let a user decide whether to wait, steer, take over, or start a related task.
Progress updates can protect scope
Concise updates also prevent scope creep. When an agent states, “I found an adjacent issue, but it is outside the requested task,” it gives the user a clean choice. The agent can keep working on the assigned outcome instead of expanding the problem surface in silence.
That is especially important in coding and research workflows. A tool call can uncover many possible improvements. A progress contract does not authorize the agent to take them all. It records the discovered option, keeps it separate from the active objective, and lets the user decide whether it belongs in the current work.
The same rule applies to delays. An agent should not say “almost done” to keep a user waiting. It should say what phase is incomplete, why it matters, and what it will do next.
Measure progress-quality, not message volume
An agent product can evaluate updates with a few practical questions:
- State accuracy: Did each update correctly represent the task's real lifecycle state?
- Outcome density: Did the update contain a concrete result or decision-relevant change, rather than routine activity narration?
- Intervention clarity: Could a user tell when a correction, approval, or cancellation would change the work?
- Terminal honesty: Did the final update distinguish completion from partial completion, blocking, failure, or cancellation?
- Privacy discipline: Did the update omit private context, sensitive identifiers, credentials, and unnecessary implementation detail?
- Update burden: Did the agent communicate at meaningful boundaries without overwhelming the user with chatter?
The aim is not to maximize update frequency. It is to make every update earn its place as a control affordance.
Common anti-patterns
Streaming every tool call
Routine operations are rarely decision-relevant. Stream outcomes and phase changes instead.
Treating a preamble as proof of progress
“I will check this” is useful at the start, but it is not evidence that the check happened or changed anything.
Using fake percentages
Percentages imply a known amount of remaining work. Use them only when the workflow has a real, measurable denominator.
Reporting completed when a validation is pending
Completion must be tied to the declared success condition, not the fact that the agent produced a message.
Exposing raw reasoning or sensitive traces
Progress should help the user act. It does not need to reveal private context, model scratchwork, or security-sensitive operations.
A practical adoption path
- Define the task phases that are meaningful for one agent workflow.
- Map each phase change to a truthful state and the smallest user-relevant outcome.
- Add the six contract elements to start, blocker, decision, milestone, and terminal updates.
- Decide which facts are safe to show at each audience boundary.
- Test updates against cases with partial completion, missing approval, ambiguous tool results, and task cancellation.
- Add an explicit next safe boundary to every nonterminal update.
- Review user feedback and interruption patterns to remove updates that do not change a decision.
The durable habit is simple: tell the user what is true, what changed, what happens next, and when their choice matters.
What we are learning building Virillio Code
Virillio Code is still in development. Its high-level work on durable tasks and scoped interaction suggests a reusable lesson: progress is not a decorative stream around an agent. It is how a user recognizes and exercises control while work remains in motion.
Sources and further reading
- A2A Protocol Specification — A Task has optional artifacts and a status object containing a required lifecycle state plus optional message and timestamp.
- OpenAI Model Guidance — Tool preambles can give users an initial useful status update and make tool use easier to follow.
- Create a model response — OpenAI API Reference — A response can run in the background and has a lifecycle status distinct from a final message.
Editorial disclosure
This article was substantially researched, drafted, and revised with AI through the Virillio Code editorial workflow. Virillio Code publishes the final text under its editorial byline, and the supporting primary sources are linked above.