> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kadoa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Kadoa Assistant

> Build, update, and monitor workflows with the Kadoa Assistant

The [Kadoa Assistant](/docs/ui/getting-started) 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](/docs/sdk/mcp). 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.

```typescript Node SDK theme={null}
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);
```

```bash REST API theme={null}
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](/api-reference/assistant/create-or-continue-session) for the complete API contract.

```text MCP Server theme={null}
> 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](/docs/sdk/notifications/overview) for configuring channels and [Change Detection](/docs/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.

```typescript Node SDK theme={null}
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);
```

```bash REST API theme={null}
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](/api-reference/assistant/send-workflow-message).

## 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. Marking the related [Inbox](/docs/sdk/inbox) item read only acknowledges it; it does not answer or resume the Assistant.

```typescript Node SDK theme={null}
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 →](/api-reference/assistant/get-pause-state)
* [Answer a question →](/api-reference/assistant/answer-question)
* [Interrupt a session →](/api-reference/assistant/interrupt-session)
* [Resume a session →](/api-reference/assistant/resume-session)
* [Stop a session →](/api-reference/assistant/stop-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.

```typescript Node SDK theme={null}
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.

```typescript Node SDK theme={null}
const strategy = await client.assistant.getStrategy("SESSION_ID");
```

* [Get the Assistant timeline →](/api-reference/assistant/get-workflow-timeline)
* [Get the latest strategy →](/api-reference/assistant/get-strategy)

## Next steps

* [Manage workflows](/docs/sdk/workflows/manage)
* [Configure notifications](/docs/sdk/notifications/overview)
* [Use the MCP Server](/docs/sdk/mcp)