Copilot architecture

How the in-editor AI assistant is wired — modes, tools, streaming, context, and the external Copilot backend dependency.

Copilot is the in-editor assistant that helps users build, edit, and reason about their workflows. This page documents how it's wired.

For the product-level guide — what each mode does, depth levels, when to use which — see Copilot.

High-level flow

External dependency: the Copilot Backend

Self-hosted clusters need outbound access to copilot.scrydon.com for Copilot to function. If your cluster is air-gapped or denies that egress, Copilot is unavailable; the rest of the platform is unaffected.

Copilot orchestration runs on a Scrydon-managed service (copilot.scrydon.com). The Scrydon API forwards user prompts to it; the Copilot Backend builds the LLM request, calls the chosen model, and streams responses back. Your cluster never ships model context to a third party — the Copilot Backend uses whichever model your org has configured for it.

For self-hosted deployments:

Go to scrydon.com → Settings → Copilot and generate a Copilot API key.
Set COPILOT_API_KEY in your self-hosted environment to that value.
Make sure PUBLIC_APP_URL and AUTH_URL resolve from outside your cluster (e.g. via a public DNS record or a tunnel). The Copilot Backend calls your cluster back during tool execution.

Modes

Mode	API value	Tools	Key behaviour
Ask	`ask`	Search, docs	Q&A with citations. Does not edit your workflow.
Build	`agent`	All tools	Proposes edits (add blocks, wire variables, change settings). Edits apply on your approval.
Plan	`plan`	Planning + todos	Drafts a multi-step plan with checklist items before any edit.

The mode dropdown shows "Build" in the UI but sends agent on the wire — kept for backward compatibility.

Tool categories

Copilot can invoke two kinds of tools:

Client tools — run in the browser. They read or modify the workflow on the canvas (run-workflow, edit-workflow, get-block-config, knowledge-base, navigate-to, …).
Server tools — run in your cluster against your integrations. Any tool exposed by an installed vendor is callable from Copilot when permission allows.

Server tools always require user confirmation by default. The user can opt into auto-allow per session.

Context system (`@mentions`)

The user can attach typed context to a Copilot message:

Context	What it injects
`@workflow`	Another workflow's full definition
`@current_workflow`	The active workflow's state
`@blocks`	Specific selected blocks
`@logs`	Execution logs for debugging
`@knowledge`	A knowledge-base entry
`@templates`	A workflow template
`@docs`	A Scrydon documentation page
`@past_chat`	A previous Copilot conversation

Context resolution happens on the API side before the request leaves the cluster, so the Copilot Backend never sees raw object IDs — only the resolved payloads.

Checkpoints

Every Copilot message that mutates the workflow records a checkpoint. From the chat panel you can revert to any previous checkpoint and the canvas snaps back to that state. Useful when an agent edit goes sideways.

GET /api/copilot/checkpoints — list checkpoints for a chat.
POST /api/copilot/checkpoints/revert — restore workflow state from a checkpoint.

Model selection

The model dropdown in Copilot is a curated list — independent of the org's main integration registry — so a user can pick a different model for "build" than they use in their agent blocks. Title generation and short utility calls use a smaller default model.

Copilot — product guide and depth levels.
Architecture → Cortex — how LLM calls from inside the cluster are routed.
Security → Audit logging — every Copilot edit is auditable.

Copilot architecture

On this page