Skip to content

docs(ai-chat): headStart handover for custom agents + triggerConfig#3964

Open
ericallam wants to merge 1 commit into
mainfrom
docs/chat-headstart-custom-backends
Open

docs(ai-chat): headStart handover for custom agents + triggerConfig#3964
ericallam wants to merge 1 commit into
mainfrom
docs/chat-headstart-custom-backends

Conversation

@ericallam

@ericallam ericallam commented Jun 16, 2026

Copy link
Copy Markdown
Member

Summary

chat.headStart now works with the chat.customAgent and chat.createSession backends (not just chat.agent), and takes a triggerConfig option. These docs cover both.

The Fast starts guide gets a "Handover with custom agents" section showing how each backend consumes the handover (consumeHandover returning { isFinal, skipped } for custom agents, turn.handover for createSession), including threading originalMessages so a resumed tool round merges into the handed-over assistant. The chat.headStart API section documents triggerConfig (tags, queue, machine, and the rest) on the auto-triggered run.

The reference picks up ChatTurn.handover, turn.complete() with no source, chat.waitForHandover, and a new HeadStartHandlerOptions table.

Docs for the SDK changes in #3963.

@changeset-bot

changeset-bot Bot commented Jun 16, 2026

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: ccce5f1

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@coderabbitai

coderabbitai Bot commented Jun 16, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Review Change Stack

Walkthrough

The documentation for the AI chat module is updated to introduce a handover mechanism between chat.headStart and custom agents. The ChatTurn type gains a handover: { isFinal: boolean } | null field (present only on turn 0), and the complete method is updated to make source optional for final handover scenarios. The chat.headStart API signature is extended with an optional triggerConfig parameter accepting Partial<SessionTriggerConfig>. A new HeadStartHandlerOptions reference section is added, along with a chat.waitForHandover entry in the chat namespace table. A new "Handover with custom agents" guide section covers turn-0 handling, step execution, and warm-partial splicing via originalMessages.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Description check ⚠️ Warning The PR description lacks several required sections from the template: Closes link, Testing section, and Changelog section. Only Summary is provided. Add the missing template sections: include 'Closes #' link, describe testing steps in Testing section, and add a Changelog entry summarizing changes.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title accurately summarizes the main changes: documenting headStart handover support for custom agents and the new triggerConfig parameter.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

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

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/chat-headstart-custom-backends

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.

❤️ Share

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

coderabbitai[bot]

This comment was marked as resolved.

Sign in to view

@mintlify

mintlify Bot commented Jun 16, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated (UTC)
trigger 🟢 Ready View Preview Jun 16, 2026, 12:29 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

@ericallam ericallam marked this pull request as ready for review June 16, 2026 14:03
devin-ai-integration[bot]
devin-ai-integration Bot reviewed Jun 16, 2026
View reviewed changes

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Devin Review found 1 potential issue.

Open in Devin Review

Comment thread docs/ai-chat/reference.mdx
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@coderabbitai coderabbitai[bot] coderabbitai[bot] left review comments

@devin-ai-integration devin-ai-integration[bot] devin-ai-integration[bot] left review comments

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@ericallam