Skip to content

docs: correct toAi() reference and document conversational context - #294

Merged
lmajano merged 1 commit into
v8.xfrom
claude/ai-routing-conversational-context
Aug 17, 2026
Merged

docs: correct toAi() reference and document conversational context#294
lmajano merged 1 commit into
v8.xfrom
claude/ai-routing-conversational-context

Conversation

@lmajano

@lmajano lmajano commented Aug 17, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Rewrites the-basics/routing/routing-dsl/ai-routing.md's toAi() section, which predated the real implementation and described a fictional API surface:
    • toAi( target, [name] ) → corrected to the real single-argument toAi( runnable ) signature
    • coldbox.system.web.routing.IAiRunnable with invoke()/stream()/batch()/info() actions taking (event, rc, prc) → corrected to the real bx-ai IAiRunnable (run()/stream()/getName()/getDescription())
    • Fictional {"prompt": ..., "context": ...} / {"response": ..., "model": ..., "tokens": ...} bodies → corrected to the real {"input": ..., "params": {}, "options": {}} / {"output": ..., "success": true} shape
  • Adds a new Conversational Context section documenting the userId/conversationId/threadId resolution that toAi()'s invoke/stream/batch sub-routes now perform, merging resolved context into options and echoing threadId back via the JSON body, an X-Thread-Id header, and a leading SSE thread frame.
  • The toMCP() section and the closing "Using Both Together" section were verified accurate against the current implementation and are unchanged.

Source of truth for the conversational-context behavior: ColdBox/coldbox-platform#681

Why

Two issues, addressed together to avoid leaving corrected content next to inaccurate content on the same page:

  1. The pre-existing toAi() documentation had drifted from the actual Router.cfc implementation well before this change.
  2. coldbox-platform PR #681 added conversational-context resolution to toAi()'s sub-routes, which needed documenting.

Validation

  • Confirmed both internal links resolve relative to the page's location: ../../event-handlers/server-sent-events.mdthe-basics/event-handlers/server-sent-events.md, and ../../../digging-deeper/ai/agentic-coldbox.mddigging-deeper/ai/agentic-coldbox.md. Both files exist in the repo.
  • Confirmed the #conversational-context anchor link targets the new ### Conversational Context heading added later on the same page.
  • Searched the repo for other pages linking to anchors within ai-routing.md (e.g. ai-routing.md#invoke-endpoint) — none found.
  • No SUMMARY.md changes needed — content-only edit to an already-listed page.

Generated by Claude Code

The existing toAi() documentation predated the real implementation and
described a fictional interface: a toAi(target, name) signature, a
coldbox.system.web.routing.IAiRunnable with invoke/stream/batch/info(event,
rc, prc) actions, and {prompt, context} request bodies. None of that matches
the actual bx-ai IAiRunnable (run/stream/getName/getDescription) or the real
{input, params, options} request shape. Rewrites the toAi() section to match
the real implementation, and adds the new userId/conversationId/threadId
conversational context support merged in coldbox-platform PR #681 - resolved
server-side, merged into options before the runnable is called, and echoed
back via the JSON response, an X-Thread-Id header, and a leading SSE
"thread" frame.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017tigigAXbCK3JEuvn5c32R
@lmajano
lmajano merged commit f0241c5 into v8.x Aug 17, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants