> ## 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.

# Work with the agent

> Change and fix workflows, answer the agent's questions, and create real-time monitors from the dashboard, code, or your AI tool.

Step-by-step tasks for Kadoa's agent in the dashboard, from code, and over MCP. For what the agent does and how its two chats differ, see [Agent](https://docs.kadoa.com/docs/agent.md).

## Before you begin

* The agent works in the dashboard, the Node SDK, the REST API, and the [Kadoa MCP server](https://docs.kadoa.com/docs/sdk/mcp.md). It is not available in the Python SDK yet.
* The SDK namespace (`client.assistant`), the API paths, and the MCP tool names say `assistant`. They control the same agent.
* Agent requests from code are asynchronous. Save the returned workflow, session, and thread IDs. Use them to check the agent's current state or a pending question.

## Open the agent

In the dashboard:

1. Select **Agent** in the bottom-right corner of any page.
2. Select **This workflow** to work on the workflow you have open, or **Workspace** for everything else. See [Two chats](https://docs.kadoa.com/docs/agent.md#two-chats).

## Change or fix a workflow

Send the agent a change request instead of deleting and recreating the workflow. The workflow keeps its ID. The agent investigates, makes the change, and reruns a sample so you can confirm the fix before anything goes live.

**Dashboard**

1. Open the workflow and select **Agent**.
2. Describe what is wrong and what you expected, for example *"The salary field is empty on most rows, but the postings show a salary near the title."*

   The agent looks into the workflow and adjusts the extraction, schema, navigation, or transformation. It then reruns the preview and tells you what it changed as it works.

   ![The agent working through its plan and narrating each step](https://mintcdn.com/kadoa/-Ftl9ZkRcaJ7_J-T/images/assistant/build.png?fit=max\&auto=format\&n=-Ftl9ZkRcaJ7_J-T\&q=85\&s=8b631a86945d123dd98fd3243c4e1c62)
3. Check the updated sample rows.

   ![The review state: a table of sample rows with Approve and Report problem actions, and a note that no quota is used until you approve](https://mintcdn.com/kadoa/-Ftl9ZkRcaJ7_J-T/images/assistant/sample.png?fit=max\&auto=format\&n=-Ftl9ZkRcaJ7_J-T\&q=85\&s=86fff969027223f472aff4fd63ea9875)
4. If the sample looks right, select **Approve** to apply the change. If not, reply with what is still off and the agent reruns. Repeat as many times as you need.

**SDK & API**

The request keeps the workflow ID and either reuses or starts its customer-facing agent 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](https://docs.kadoa.com/api-reference/assistant/send-workflow-message.md).

**MCP**

Ask your AI tool, for example:

```text theme={null}
> On my Products workflow, include the product SKU and keep paginating until there are no more products.
```

Your AI tool uses `request_workflow_update`. Use it to change what the agent extracts or how it navigates.

The agent can investigate and fix issues across the whole workflow:

| If you see... | Ask the agent to... |
| - | - |
| A field that is empty or wrong | Find the value on the page and extract it correctly |
| Rows missing or pagination stopping early | Keep paginating until there are no more results |
| A run that looks stale or returned too little | Look into why and fix it |
| Output in the wrong format | Normalize a field, for example dates to `YYYY-MM-DD` |
| A source that started returning blocked or empty pages | Investigate the access issue and adapt |
| The wrong fields, schedule, alerts, or monitored fields | Change the schema, [schedule](https://docs.kadoa.com/docs/workflows/scheduling.md), [notifications](https://docs.kadoa.com/docs/notifications.md), or [monitoring](https://docs.kadoa.com/docs/change-detection.md) |

For automatic checks on every run instead of spot-fixing, add [data quality](https://docs.kadoa.com/docs/data-quality.md) rules.

## Answer the agent's question

The agent can pause to ask for clarification. A workflow waiting on you shows **Reply needed**, and a dot appears on **Agent**. After you answer, the agent resumes.

**Dashboard**

1. Open the workflow that shows **Reply needed**.
2. Select **Open agent**.
3. Pick an answer, or select **Other** and type your own. Some questions take free text instead.
4. Select **Submit**.

**SDK & API**

Read the 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`. See [Manage workflows](https://docs.kadoa.com/docs/workflows/manage.md). Workflows with an open support ticket are listed under `group:support` instead, even when a question is pending.

```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. Do not call `resume()` for a pending question. It is for an inactive or interrupted session.

* [Get pause state →](https://docs.kadoa.com/api-reference/assistant/get-pause-state.md)
* [Answer a question →](https://docs.kadoa.com/api-reference/assistant/answer-question.md)

**MCP**

Ask your AI tool, for example:

```text theme={null}
> Which of my workflows are waiting for my answer?
```

Your AI tool finds them with `list_workflows` and the `group:attention` filter. It reads the question with `get_workflow_assistant` and sends your reply with `answer_workflow_assistant_question`.

## Create a real-time monitor

Use a real-time monitor when you want continuous change detection and alerts. It is a separate workflow mode. Do not convert a scheduled workflow to real-time by changing its interval.

A real-time monitor needs at least one notification channel.

**Dashboard**

1. Select **Agent**. If the chat shows **This workflow**, select **Workspace**.
2. Name the pages to watch, the changes you care about, and the channel for alerts. For example, *"Monitor product prices on [https://example.com/products](https://example.com/products) and alert me by email when they change."*

The agent creates one monitor per website.

To build a single monitor from the setup prompt instead, select **Real-time** as the workflow type. See [Use the setup prompt](https://docs.kadoa.com/docs/workflows/prompts.md#use-the-setup-prompt).

**SDK & API**

The API persists notification settings before it starts the agent. 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 agent session](https://docs.kadoa.com/api-reference/assistant/create-or-continue-session.md) for the complete API contract.

**MCP**

Ask your AI tool, for example:

```text theme={null}
> Monitor prices on https://example.com/products and notify me by email when they change.
```

Your AI tool uses `create_realtime_monitor`. It saves the notification settings first, then starts the agent.

For scheduled and one-time extractions, notifications are optional. See [Notifications](https://docs.kadoa.com/docs/notifications.md) to configure channels and [Change detection](https://docs.kadoa.com/docs/change-detection.md) for how Kadoa identifies changes.

## Pause or stop agent work

Interrupting or stopping the agent controls agent work only. It does not pause or resume the workflow schedule, and stopping does not delete the workflow.

**Dashboard**

1. While the agent works, select **Interrupt** below the chat.
2. To continue, send a message with new instructions or select **Continue**.

**SDK & API**

`client.assistant.interrupt()`, `resume()`, and `stop()` each take the session ID. Use `resume()` for an inactive or interrupted session.

* [Interrupt a session →](https://docs.kadoa.com/api-reference/assistant/interrupt-session.md)
* [Resume a session →](https://docs.kadoa.com/api-reference/assistant/resume-session.md)
* [Stop a session →](https://docs.kadoa.com/api-reference/assistant/stop-session.md)

**MCP**

Ask your AI tool, for example:

```text theme={null}
> Stop the agent on my Products workflow
```

Your AI tool uses `interrupt_workflow_assistant`, `resume_workflow_assistant`, or `stop_workflow_assistant`.

## Read the conversation and strategy

The timeline shows customer-visible messages and clarification questions. It excludes internal and operations activity. In the dashboard, the workflow chat shows the same conversation.

**SDK & API**

Pass `nextCursor` from one response as `cursor` to read older entries.

```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 agent timeline →](https://docs.kadoa.com/api-reference/assistant/get-workflow-timeline.md)
* [Get the latest strategy →](https://docs.kadoa.com/api-reference/assistant/get-strategy.md)

**MCP**

Ask your AI tool, for example:

```text theme={null}
> What did the agent say on my Products workflow, and which strategy did it use?
```

Your AI tool uses `get_workflow_assistant_timeline` and `get_workflow_strategy`.

## Use Workspace chat

Workspace chat is for work that spans workflows. It is dashboard-only, and API keys cannot open it. It uses the same tools and role permissions as the [Kadoa MCP server](https://docs.kadoa.com/docs/sdk/mcp.md). Your AI tool can do the same work over MCP. Either way, build and repair work goes to the same agent.

1. Select **Agent**. If the chat shows **This workflow**, select **Workspace**.
2. Type your request and send it.

To start a new chat, select **+**. To open or delete past chats, select **History**.

### Ask about your team's workflows

Ask about any workflow, run, or change. Try *"Which workflows failed this week?"* or *"Who changed the schedule on Job Postings?"*

![A Workspace chat answering which workflows ran today and how many rows each returned](https://mintcdn.com/kadoa/-Ftl9ZkRcaJ7_J-T/images/assistant/workspace-chat.png?fit=max\&auto=format\&n=-Ftl9ZkRcaJ7_J-T\&q=85\&s=54e0db5f1aa931f40f35892e6ce0c51b)

### Create workflows in batch

Name several websites in one message, such as *"Track job postings (title, location, salary, apply link) on acme.com/careers, globex.com/jobs, initech.com/open-roles"*. The agent proposes a shared [template](https://docs.kadoa.com/docs/templates.md) and the website list. Confirm, or name an existing template to reuse. The agent then creates one workflow per website and reports any failures. Each workflow previews for you to approve.

For real-time monitoring, the agent creates one monitor per website. This needs a notification channel.

### Find sources

Describe the data, such as *"Find me sources for UK planning applications"*. The agent searches the web and opens pages in a browser when needed. It lists candidate URLs with what each likely carries and what it checked. A workflow run confirms the data. The agent never submits forms that change anything or enters credentials.

![A Workspace chat answering a request for European fintech career pages: ten candidate URLs, each marked as company-run or job board, with what each page shows](https://mintcdn.com/kadoa/v7EEuXHZHS8J6dQ7/images/assistant/workspace-research.png?fit=max\&auto=format\&n=v7EEuXHZHS8J6dQ7\&q=85\&s=4be09a346e941ea1cbecdb3f0f65c5ac)

## What to say

Brief the agent like a colleague. Lead with the symptom and the result you expect. Name the field, the page, and what the correct value should look like. The same advice as [writing a good prompt](https://docs.kadoa.com/docs/workflows/prompts.md) applies.

| Vague | Specific |
| - | - |
| "The data is broken." | "Since yesterday the `price` field is null on every row. The source still shows a price on each product page." |
| "Get more data." | "Open each fund profile and extract name, strategy, AUM, and inception date. Continue until there are no more results." |
| "Fix the dates." | "`published_date` comes back as free text like 'June 3, 2026'. Normalize it to YYYY-MM-DD." |

> [!TIP]
>
> In a workflow chat, type `$` to reference a saved [variable](https://docs.kadoa.com/docs/workflows/variables.md), such as a login value. Type `@` for a notification channel or `#` for a tag. See [Use the setup prompt](https://docs.kadoa.com/docs/workflows/prompts.md#use-the-setup-prompt).

> [!TIP]
>
> Rules you repeat on every workflow belong in [AI personalization](https://docs.kadoa.com/docs/ui/ai-personalization.md) instead. The agent reads them when it starts on a new workflow.

## When the agent can't fix it

The agent tells you and automatically hands the issue to [Kadoa support](https://docs.kadoa.com/docs/support-center.md). For how Kadoa classifies and auto-recovers failed runs, see [Error handling](https://docs.kadoa.com/docs/workflows/error-handling.md).

## Related

* [Prompts](https://docs.kadoa.com/docs/workflows/prompts.md)
* [Preview and approval](https://docs.kadoa.com/docs/ui/workflows/human-in-the-loop.md)
* [Manage workflows](https://docs.kadoa.com/docs/workflows/manage.md)
* [Data quality](https://docs.kadoa.com/docs/data-quality.md)
* [AI personalization](https://docs.kadoa.com/docs/ui/ai-personalization.md)
* [Kadoa MCP server](https://docs.kadoa.com/docs/sdk/mcp.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.