Kadoa Assistant

Build, update, and monitor workflows with the Kadoa Assistant

The Kadoa Assistant builds workflows from instructions and can update an existing workflow. Assistant requests are asynchronous: save the returned workflow, session, and thread IDs, then check the Assistant when you need its current state or a pending question.

The Assistant is available in the Node SDK, REST API, and MCP Server. It is not currently available in the Python SDK.

Create a realtime monitor

Use a realtime monitor when you want continuous change detection and alerts. It is a separate workflow mode: do not convert a scheduled workflow to realtime by changing its interval.

Realtime monitor creation requires at least one notification channel. The API persists notification settings before it starts the Assistant, so a successful response includes the workflow, session, and thread to use for follow-up.

Node SDK

import { KadoaClient } from "@kadoa/node-sdk";

const client = new KadoaClient({ apiKey: "YOUR_API_KEY" });

const created = await client.assistant.createRealtimeWorkflow({
  instructions: "Monitor product prices on https://example.com/products and alert me when they change.",
  notificationChannelIds: ["NOTIFICATION_CHANNEL_ID"],
});

console.log(created.workflowId, created.sessionId, created.threadId, created.jobId);

REST API

curl -X POST "https://api.kadoa.com/v5/agent" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Monitor product prices on https://example.com/products and alert me when they change.",
    "productType": "realtime",
    "notificationChannelIds": ["NOTIFICATION_CHANNEL_ID"]
  }'

See create or continue an Assistant session for the complete API contract.

MCP Server

> Monitor prices on https://example.com/products and notify me by email when they change.

For scheduled and one-time extractions, notifications are optional. See Notifications for configuring channels and Change Detection for how changes are identified.

Update an existing workflow

Send a change request to the workflow Assistant instead of deleting and recreating the workflow. The request keeps the workflow ID and either reuses or starts its customer-facing Assistant session.

Node SDK

const accepted = await client.assistant.requestWorkflowUpdate("WORKFLOW_ID", {
  instructions: "Include the product SKU and keep paginating until there are no more products.",
});

console.log(accepted.sessionId, accepted.threadId, accepted.jobId);

REST API

curl -X POST "https://api.kadoa.com/v5/agent/workflows/WORKFLOW_ID/assistant/messages" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Include the product SKU and keep paginating until there are no more products."}'

See the send a workflow message API reference.

Check status and answer questions

An Assistant can pause to ask for clarification. Read its pause state, then answer the current question with the returned session, question, and optional thread IDs. To find the workflows waiting on you, filter the workflow list with statusFilters=group:attention, as shown in Find workflows that need attention. Workflows with an open support ticket are listed under group:support instead, even when a question is pending.

Node SDK

const state = await client.assistant.getPauseState("SESSION_ID");

if (state.pendingQuestion) {
  await client.assistant.answerQuestion({
    sessionId: "SESSION_ID",
    threadId: state.pendingQuestion.threadId,
    questionId: state.pendingQuestion.questionId,
    answers: { "0": "Use the US store." },
  });
}

Answering a question requests its resume. resume() is for an inactive or interrupted session, not for a pending question. interrupt() and stop() control Assistant work only; they do not pause or resume the workflow schedule.

• Get pause state →
• Answer a question →
• Interrupt a session →
• Resume a session →
• Stop a session →

Read the conversation and strategy

Use the timeline to show customer-visible messages and clarification questions. Pass nextCursor from one response as cursor to read older entries. The timeline excludes internal and operations activity.

Node SDK

const timeline = await client.assistant.getTimeline("WORKFLOW_ID", { limit: 50 });

for (const item of timeline.items) {
  console.log(item.time, item.kind);
}

if (timeline.pagination.hasMore) {
  const older = await client.assistant.getTimeline("WORKFLOW_ID", {
    cursor: timeline.pagination.nextCursor ?? undefined,
  });
  console.log(older.items);
}

When a build has produced a customer-safe strategy, you can retrieve its approach, data source, and realtime interval. A null strategy means the session exists but has not produced one yet.

Node SDK

const strategy = await client.assistant.getStrategy("SESSION_ID");

• Get the Assistant timeline →
• Get the latest strategy →

Next steps

• Manage workflows
• Configure notifications
• Use the MCP Server