Work with the agent

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.

Before you begin

The agent works in the dashboard, the Node SDK, the REST API, and the Kadoa MCP server. 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:

Select Agent in the bottom-right corner of any page.
Select This workflow to work on the workflow you have open, or Workspace for everything else. See 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
SDK & API
MCP

Open the workflow and select Agent.
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.
Check the updated sample rows.
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.

The request keeps the workflow ID and either reuses or starts its customer-facing agent session.

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);

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.

Ask your AI tool, for example:

> 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, notifications, or monitoring

For automatic checks on every run instead of spot-fixing, add data quality 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
SDK & API
MCP

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

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

Ask your AI tool, for example:

> 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
SDK & API
MCP

Select Agent. If the chat shows This workflow, select Workspace.
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 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.

The API persists notification settings before it starts the agent. A successful response includes the workflow, session, and thread to use for follow-up.

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);

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 for the complete API contract.

Ask your AI tool, for example:

> 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 to configure channels and Change detection 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
SDK & API
MCP

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

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

Ask your AI tool, for example:

> 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
MCP

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

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");

Ask your AI tool, for example:

> 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. Your AI tool can do the same work over MCP. Either way, build and repair work goes to the same agent.

Select Agent. If the chat shows This workflow, select Workspace.
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

A Workspace chat answering which workflows ran today and how many rows each returned

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

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

In a workflow chat, type $ to reference a saved variable, such as a login value. Type @ for a notification channel or # for a tag. See Use the setup prompt.

Rules you repeat on every workflow belong in AI personalization 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. For how Kadoa classifies and auto-recovers failed runs, see Error handling.

Get started

Concepts

Security & Compliance

Build workflows

Templates

Monitor & alert

MCP

Integrations

Administration

Before you begin

Open the agent

Change or fix a workflow

Answer the agent’s question

Create a real-time monitor

Pause or stop agent work

Read the conversation and strategy

Use Workspace chat

Ask about your team’s workflows

Create workflows in batch

Find sources

What to say

When the agent can’t fix it

​Before you begin

​Open the agent

​Change or fix a workflow

​Answer the agent’s question

​Create a real-time monitor

​Pause or stop agent work

​Read the conversation and strategy

​Use Workspace chat

​Ask about your team’s workflows

​Create workflows in batch

​Find sources

​What to say

​When the agent can’t fix it

​Related

Before you begin

Open the agent

Change or fix a workflow

Answer the agent’s question

Create a real-time monitor

Pause or stop agent work

Read the conversation and strategy

Use Workspace chat

Ask about your team’s workflows

Create workflows in batch

Find sources

What to say

When the agent can’t fix it

Related