Add progress updates documentation for tool calls (AIT-312) by matt423 · Pull Request #3167 · ably/docs

matt423 · 2026-01-30T11:32:54Z

Description

Add Progress updates section which details the two approaches(messages & LiveObjects) and provides details and comparisons of the two approaches. Claude assisted but verified the code samples and writing.

Review App

Copilot Summary

This pull request adds comprehensive documentation on how to implement progress updates for long-running tool calls in the messaging system. It introduces two main approaches—using messages and LiveObjects—for reporting and tracking tool execution progress, with detailed code examples and guidance on when to use each method.

Progress updates documentation:

Added a new section describing how to stream progress updates for long-running tool calls, including the benefits for user experience and execution visibility.

Progress via messages:

Provided step-by-step examples for publishing and subscribing to tool_progress messages, demonstrating how to correlate updates with specific tool calls and update the UI accordingly.

Progress via LiveObjects:

Documented how to use LiveObjects (including LiveMap and LiveCounter) for real-time, state-based progress tracking, with code samples for both publishing and subscribing to progress state.
Included notes on enabling LiveObjects capability and the benefits of LiveCounter for distributed/concurrent updates.

Guidance and best practices:

Added a comparison table and recommendations for when to use messages versus LiveObjects, and illustrated how both approaches can be combined for comprehensive progress tracking.

Checklist

Commits have been rebased.
Linting has been run against the changed file(s).
The PR adheres to the writing style guide and contribution guide.

Summary by CodeRabbit

Documentation
- Added comprehensive "Progress updates" documentation explaining two approaches for managing long-running tool calls: using Messages for discrete updates and LiveObjects for continuous numeric progress, including detailed code examples for publishing and subscribing to progress events.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

coderabbitai · 2026-01-30T11:33:01Z

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

🔍 Trigger a full review

Walkthrough

Added comprehensive documentation section on delivering progress updates for long-running tool calls in the AI Transport messaging guide. Explains two approaches: Messages for discrete updates and LiveObjects for continuous numeric progress, with code examples and usage guidance.

Changes

Cohort / File(s)	Summary
Progress Updates Documentation `src/pages/docs/ai-transport/messaging/tool-calls.mdx`	Added "Progress updates" section with detailed explanations of two patterns for tool call progress reporting (Messages vs. LiveObjects), including code examples for publishing and subscribing, and guidance on when to use each approach.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 Hop along through progress updates clear,
Messages dance, LiveObjects appear,
Long-running tools now have their way,
To whisper progress, come what may!
Documentation blooms, examples shine,
Your tool calls march in perfect time. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	❓ Inconclusive	The PR introduces duplicated content (two identical progress-updates sections), which is a potential quality issue but not out-of-scope since all changes relate to the linked issue objective.	Review and remove the duplicated progress-updates section to ensure the documentation is clean and not redundant.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: adding documentation for progress updates in tool calls, with issue reference for context.
Linked Issues check	✅ Passed	The PR addresses all core requirements from AIT-312: documenting progress updates for tool calls, comparing messages vs LiveObjects approaches, and providing concrete implementation examples.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch ait-312-tool-call

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

matt423 · 2026-01-30T11:38:49Z

@coderabbitai review

coderabbitai · 2026-01-30T11:38:57Z

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

coderabbitai

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@src/pages/docs/ai-transport/messaging/tool-calls.mdx`:
- Around line 360-386: The subscription callback in channel.subscribe uses
toolCallId from message.extras.headers without checking for its presence, which
can cause toolProgress entries to be stored under undefined and collide; update
the callback in channel.subscribe to early-return when toolCallId is
null/undefined (or otherwise falsy) before calling toolProgress.set/get/delete
or renderProgressBar/renderCompleted so all cases ('tool_call', 'tool_progress',
'tool_result') safely skip processing when toolCallId is missing.