# Overview

What conversations are and how to drive agent work programmatically.



A **conversation** is a job assigned to a single agent — an ordered list of messages (user, assistant, and system) plus a status that tracks the agent's progress. Conversations are how you trigger work programmatically instead of typing into Slack, Discord, or the dashboard.

## How it works [#how-it-works]

1. Start a conversation with `POST /conversations/start`, passing an `agent_id` and an initial `prompt`. The API returns a `job_id` and the `message_id` of your prompt.
2. The agent picks up the job and appends `assistant` messages as it works. You can poll a single message or list all messages on the job.
3. To send a follow-up, call `POST /conversations/{job_id}/continue`. Only API-started jobs can be continued via the API — jobs created from Slack, Discord, or the web UI are off-limits.

## When to use it [#when-to-use-it]

* **Embed Nairi as the AI layer in your own product.** Run an agent on behalf of an end user and render the conversation in your UI.
* **Kick off agent work from your own systems.** Trigger conversations from CI pipelines, webhooks, cron, or backend services — no human in the loop.

## Modes [#modes]

* `execute` (default) — agent has full tool access.
* `ask` — agent answers without invoking tools.

See [Message reference](/api/conversations/message-reference) for the full list of message roles and statuses returned by the message endpoints.