Quickstart: your first agent run

Generate a complete module from a prompt — and understand the async pattern every integration uses.

With a client connected, make Vidext do something real: create a complete module through the write-capable operator tool, without a separate outline-confirmation turn.

The one-prompt version

In your connected client, say:

Create a beginner-friendly module about incident response for new
on-call engineers.

Your agent calls ask_operator with your prompt and a unique idempotencyKey. Because the request explicitly asks to create a module, the operator plans internally and starts the builder as one flow. Each call returns a run envelope, not a terminal build result:

{
  "organizationId": "org_...",
  "organizationSlug": "...",
  "chatId": "chat_...",
  "agentName": "...",
  "run": {
    "requestId": "...",
    "traceId": "...",
    "agentRequestId": "...",
    "modelId": "grok/grok-4.3",
    "mutationLevel": "write",
    "availableToolNames": ["..."],
    "ids": {
      "moduleIds": ["018f1111-2222-7333-8444-555555555555"],
      "courseIds": [],
      "plannerRunIds": ["..."],
      "builderRunIds": []
    },
    "nextAction": {
      "tool": "get_operation",
      "arguments": { "moduleId": "018f1111-2222-7333-8444-555555555555", "operationId": "operation_..." },
      "pollAfterMs": 1500
    }
  }
}

Planning and build work run asynchronously. Wait at least nextAction.pollAfterMs, then call get_operation with nextAction.arguments; repeat while another next action is returned.

A finished build means a draft is ready for human review in the Vidext app — publishing remains a human decision.

What actually happened

Plan internally

The operator produces one source-grounded Markdown content plan (plannerRunId identifies this run). That plan is the durable semantic artifact; the builder compiles the medium-specific module structure from it without presenting a separate approval step for an explicit creation request.

Build

The validated planner handoff starts the builder automatically. Builds take minutes and run server-side; narrative, text, layouts, and interactions become available before the remaining media finishes, and the completed draft is pushed back into the chat (builderRunId identifies this run).

The pattern to internalize: follow `nextAction`

Planning and builds are asynchronous: a turn returns immediately, and you drive it to completion by following run.nextAction with get_operation. Every robust integration:

Waits for pollAfterMs, calls the named get_operation tool with its typed arguments, and repeats until nextAction is gone.
Keeps run.ids (moduleIds, plannerRunIds, builderRunIds) so support can trace the run.

Level up

Plan-only: ask the operator for a plan or outline without asking it to create or build. It returns the plan in chat and creates no module or build.
Ground in documents: upload or connect sources in the Vidext app first, then reference them through the document-grounded flow.
Edit a finished module: ask the operator to edit the built module — it applies validated changes via its edit tools.

Recommended flows

The canonical sequences for every scenario.

Errors, limits, and async

What failure looks like and how to handle it.