ait: refactor Temporal framework page - #3500
Conversation
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
417fe1d to
3ecacc9
Compare
3ecacc9 to
86160b9
Compare
zknill
left a comment
zknill
left a comment
There was a problem hiding this comment.
This PR predominantly ports getting started info over to the temporal page.. but looking at the other temporal integrations. they all talk about
- Opening lines explaining an integration between [some thing] and temporal.. or Temporal and [something]
- Explain what you get by using that integration
- https://docs.temporal.io/develop/go/integrations/google-adk
- https://docs.temporal.io/develop/typescript/integrations/ai-sdk
- https://adk.dev/integrations/temporal/
- https://github.com/temporalio/sdk-python/blob/main/temporalio/contrib/openai_agents/README.md
Can you review the page, and imagine that you know nothing about ably (or only very little), and that you navigated to this page from Temporal's integration list and you're trying to figure out a) what this gives you and b) how it works and c) how to implement it
86160b9 to
289f317
Compare
|
@zknill I agree that I missed explanation section. But not sure, I agree that for example https://docs.temporal.io/develop/go/integrations/google-adk is very well explain what you get, and that person that know nothing about adk, can understand a thing (the prerequisites section of every guide states that you should be familiar with adk, ai-sdk, pedantic ai, etc.). I tried to rephrase doc, add more explanations, so person unfamiliar with ably will get the picture. Can you check? |
e53b9c2 to
7b28da8
Compare
| Moving an agent into a Temporal workflow makes its execution durable and breaks the simplest path back to the browser. One HTTP handler could hold a response open and write tokens down it as the model produced them. A workflow cannot: the POST that started it returned immediately, the model call is running on whichever worker picked up the activity, and the browser waiting for an answer has nothing left to read from. | ||
|
|
||
| Ably AI Transport gives the conversation a session of its own, a durable stream that belongs to the conversation rather than to a request or a worker. Your activities publish the agent's output to it as the model produces it, and every browser attached to it receives that output in realtime. Because the conversation outlives the request, a user who reconnects rejoins the answer mid-flight, a second device shows the same conversation, and a stop button on either one reaches the activity that is calling the model. | ||
|
|
||
| Temporal keeps the execution alive: it persists a workflow's progress, retries a failed activity in a fresh process, and reschedules work when a worker dies. The two systems meet on a single identifier. Each activity publishes its output as one [step](/docs/ai-transport/concepts/runs#steps), and that step takes the activity's own id, so when Temporal retries an activity the retry lands under the same id and replaces the failed attempt's partial output instead of appending beside it. The user sees one answer, not two half-written ones. | ||
|
|
||
|  | ||
|
|
||
| ## What Temporal brings <a id="temporal-brings"/> | ||
| ## Map the model onto Temporal's <a id="model"/> | ||
|
|
||
| | Feature | Description | | ||
| | --- | --- | | ||
| | Workflow durability | The workflow's execution history persists in Temporal. A worker crash resumes the workflow on a different worker without losing progress. | | ||
| | Activity retries | Failed activities retry under configurable policies. The retry gets the same `activityId`, so Ably can supersede its predecessor. | | ||
| | Cancellation | A workflow cancel propagates as an `AbortSignal` inside each activity, which flows into the LLM call and stops it gracefully. | | ||
| | Observability | The Temporal Web UI shows activity attempts, retry counts, error traces, and workflow history. Pair it with the session to see the whole turn. | | ||
| Sessions, runs, and steps are the three concepts this page relies on. Two of them map directly onto units you already schedule in Temporal: | ||
|
|
There was a problem hiding this comment.
I'm kind of hoping for the first paragraph to go something like:
The Temporal integration with Ably AI Transport allows [...agents hosted on temporal...] to benefit from [...benefits of AI Transport...]. Ably AI Transport is build on top of Ably's Pub/Sub channels so get [...benefits of Ably channels...].
I should be able to read just that and understand if this is for me, how I will benefit, etc. We should focus on the benefits of our tech/sdks.. and worry slightly less about explaining the problem in the first paragraph. Because people who have that problem will already know it. We can explain the problem later, but it's too dominant at the start in the current text
|  | ||
|
|
||
| ## What Temporal brings <a id="temporal-brings"/> | ||
| ## Map the model onto Temporal's <a id="model"/> |
There was a problem hiding this comment.
Can you just make sure that you're actually reading / writing the words yourself too. I don't mind using AI.. but changing "What temporal brings" to "Map the model onto Temporal's" feels like an AI initiated decision/change, and not a change that you've actually chosen to make.
There was a problem hiding this comment.
The same for the opening paragraphs where we are getting words like "the http handler can write the tokens down".. which isn't words anyone would be expecting to read / useful for understand what's actually happening or not happening.
52a4cbe to
282321d
Compare
0d5daa1 to
ed57ec9
Compare
[AIT-1211] Show how the two systems compose: the Step/activity join, workflow-vs-activity boundaries, opening the Run, tool activities, timeouts and retries, cancel routing, and suspend/resume, with condensed inline code in place of the file-by-file build. Link to /docs/ai-transport/getting-started/temporal for the walkthrough. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Reorder the page so it reads top to bottom rather than as a reference. The concept mapping and cancellation behaviour come first, then a Getting started section holds the prerequisites, the install and the layout decisions, then Implement the agent walks the five pieces in order. Drop the timeout and heartbeat sizing section and the scope and trade-offs section. Both covered production tuning a reader does not need to get an agent running, and the FAQ already says what Temporal handles and what AI Transport adds on top. Explain how to choose the run id, which until now was a one-line comment inside a code sample. It has to be stable across retries, so it comes from the workflow id. Temporal's own workflowInfo().runId changes on workflow retry and on continue-as-new, so using it would open a second run each time. And the rule only covers a run the workflow opens itself, because a resumed run takes its id from the channel. Rewrite the browser sample against createClientSession and session.view instead of the React providers and hooks. Nothing on this page is React-specific, and the hooks made the client look coupled to a framework when it is not. Cancelling now goes through run.cancel(), which works before the agent has created the run id, unlike the previous lookup by run status.
0446ac8 to
d086873
Compare
2 participants
Description
AIT-1211
Show how the two systems compose: the Step/activity join, workflow-vs-activity boundaries, opening the Run, tool activities, timeouts and retries, cancel routing, and suspend/resume, with condensed inline code in place of the file-by-file build.
Checklist