[Agents] Sync recovery, context-overflow, and agent-tool docs#31251
Conversation
github-actions
Bot
added
product:agents
github-actions
Bot
assigned
elithrar,
irvinebroque,
rita3ko,
thomasgauvin and
whoiskatrin
|
This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:
|
threepointone
requested review from
a team,
elithrar,
irvinebroque,
rita3ko,
thomasgauvin and
whoiskatrin
as code owners
Review💡 0 suggestions found in commit Acknowledged by author (3)
CommandsOnly codeowners can run commands. Post a comment with the command to trigger it.
|
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
|
|
||
| ```ts | ||
| export class MyAgent extends Think<Env> { | ||
| chatRecovery = { |
There was a problem hiding this comment.
🟡 Missing override keyword on chatRecovery in code example
The new code example at src/content/docs/agents/harnesses/think/recovery.mdx:127 declares chatRecovery = { without the override keyword. Every other chatRecovery example across the codebase uses override chatRecovery = … — see recovery.mdx:31, chat-agents.mdx:586, chat-agents.mdx:602. The omission is inconsistent and will cause a compile error for users who copy this example into a project with noImplicitOverride: true in their tsconfig.json.
| chatRecovery = { | |
| override chatRecovery = { |
Was this helpful? React with 👍 or 👎 to provide feedback.
ask-bonk
Bot
added
documentation
![ask-bonk[bot]](https://avatars.githubusercontent.com/in/2454580?s=60&v=4){kind=small}
There was a problem hiding this comment.
Syncs Agents SDK docs with upstream recovery, context-overflow, and agent-tool changes. 1 suggested change and 2 comments below.
Issues:
- MEDIUM —
src/content/docs/agents/harnesses/think/lifecycle-hooks.mdx:338New baretsexample should be wrapped in<TypeScriptExample>. - MEDIUM —
src/content/docs/agents/runtime/lifecycle/sessions.mdx:432Possessive for inanimate object (model’s). - LOW —
src/content/docs/agents/runtime/operations/observability.mdx:214Past-tense description in an events table that otherwise uses present tense.
Out of scope: The onExhausted descriptions in chat-agents.mdx and recovery.mdx differ slightly (Inspect ctx.reason for why. vs Inspect ctx.reason.). Consider aligning them in a follow-up.
| When `.compactAfter(threshold)` is set, `appendMessage()` checks the estimated token count after each write. If it exceeds the threshold, `compact()` is called automatically. Auto-compaction failure is non-fatal — the message is already saved. | ||
|
|
||
| :::note | ||
| Auto-compaction is checked **between turns** (on each `appendMessage()`), not within a turn. A single long, tool-heavy turn can grow past the model's context window mid-flight, before the next check. `@cloudflare/think` adds opt-in mid-turn recovery on top of this — refer to [Context-window overflow recovery](/agents/harnesses/think/recovery/#context-window-overflow-recovery). |
There was a problem hiding this comment.
Avoid possessive for inanimate objects (style guide):
| Auto-compaction is checked **between turns** (on each `appendMessage()`), not within a turn. A single long, tool-heavy turn can grow past the model's context window mid-flight, before the next check. `@cloudflare/think` adds opt-in mid-turn recovery on top of this — refer to [Context-window overflow recovery](/agents/harnesses/think/recovery/#context-window-overflow-recovery). | |
| Auto-compaction is checked **between turns** (on each `appendMessage()`), not within a turn. A single long, tool-heavy turn can grow past the model context window mid-flight, before the next check. `@cloudflare/think` adds opt-in mid-turn recovery on top of this — refer to [Context-window overflow recovery](/agents/harnesses/think/recovery/#context-window-overflow-recovery). |
|
|
||
| Or write your own, optionally delegating to the bundled classifier: | ||
|
|
||
| ```ts |
There was a problem hiding this comment.
Wrap this new example in <TypeScriptExample> to match the bundled-classifier example above it and the style guide.
|
|
||
| | Type | Payload | When | | ||
| | ------------------------ | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | ||
| | `chat:context:compacted` | `{ reason, shortened, requestId?, attempt? }` | Think compacted the session to handle a context-window overflow. `reason` is `"proactive"` (the `contextOverflow.proactive` guard fired before a step) or `"reactive"` (`contextOverflow.reactive` fired after an overflow). `shortened` is whether compaction actually reduced history — `false` means a retry would overflow again. Refer to [Context-window overflow recovery](/agents/harnesses/think/recovery/#context-window-overflow-recovery). | |
There was a problem hiding this comment.
Use present tense to match the rest of the table ("Think compacts" instead of "Think compacted").
|
Reviewed PR #31251 and posted feedback on GitHub. Labels applied: Validation: What changed: This PR syncs the Agents SDK docs with upstream Posted review: 1 inline suggestion + 2 comments.
|
6 participants
Summary
Syncs the Agents SDK documentation with changes that landed in the
cloudflare/agentsrepository after the last docs sync (#31098). These are updates to existing pages — no new pages or moved files.The upstream changes center on durable chat recovery and a new mid-turn context-overflow recovery layer:
communication-channels/chat/chat-agentschatRecoveryconfig table,ChatRecoveryProgressContext,ctx.reasonseal values, and "Turns waiting on a human are not sealed"harnesses/think/recoveryharnesses/think/configurationcontextOverflowconfiguration rowharnesses/think/lifecycle-hooksclassifyChatErrorhook andChatErrorContext.classificationharnesses/think/client-toolsruntime/execution/agent-toolsAgentToolInterruptedReason, and theagentToolReattach*optionsruntime/operations/observabilitychat:context:compactedevent and the "Chat context events" tableruntime/lifecycle/sessionsValidated locally with
pnpm run check(0 errors) and by running the dev server — all eight pages return HTTP 200 and render the new content.Documentation checklist