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

# Agents

> Keep everything for one job in one place

An agent holds everything that does one job: its workflows, conversation flows, coworkers, knowledge bases, files and [data stores](https://docs.cogniagent.ai/features/data-stores.md). "AI Receptionist" might hold the conversation flow that answers the phone, the workflow that books the visit, and the knowledge base with your prices.

Items inside an agent use each other freely. They reach another agent's items only through the [endpoints](https://docs.cogniagent.ai/features/endpoints.md) that agent offers, and Unsorted is open to every agent. Knowledge bases, connections and files are shared by all agents, and what a person may see or change does not depend on agents. So a conversation flow runs another agent's workflow when that agent offers it, and an actor can read any knowledge base. A call with no offer is reported for now and will soon be refused: see [Calls without an offer](https://docs.cogniagent.ai/features/endpoints.md#calls-without-an-offer).

What starts an agent's work on its own, such as a webhook or a schedule, is in its **Settings → Triggers**. Where people talk to it is set in **Settings → Channels**, and what other agents and apps may call or use in **Settings → External access**. See [Triggers](#triggers), [Channels](https://docs.cogniagent.ai/features/ways-in.md) and [Endpoints](https://docs.cogniagent.ai/features/endpoints.md).

> [!NOTE]
>
> Conversation flows used to be called **Chat & Voice Agents**. Only the name changed: they work exactly as before.

## Where your work went

Everything you built before agents, except your files, is in **Unsorted**, at the bottom of the Agents list in the sidebar. It all works as before: the same addresses, webhooks, phone numbers, schedules and history. Move items into agents whenever you like; there is no deadline.

The old addresses of the workflow, conversation flow, session, coworker and knowledge base lists now open Unsorted, filtered to that kind, so your bookmarks still land. Files are under each agent, in its **Files**. See [Files](#files).

## Find your way around

The **Agents** list in the sidebar shows every agent. Click the arrow beside one to see what it holds: its workflows, conversation flows, coworkers and knowledge bases by name, then **Files**. Click its name to open its page, whose home lists everything it holds.

To find anything in any agent, type in the search box above the list.

## Create an agent

1. Click **+** beside **Agents** in the sidebar, or **New agent** on the Agents page.
2. Give it a name, such as the job it does.
3. Add items from its page or from **Add…** under its name in the sidebar.
4. Click **Start** in its header when it is ready to work. A new agent starts stopped.

Every new workflow, conversation flow, coworker and knowledge base is created inside an agent, and a coworker's sessions belong to its agent. Files are the exception: a new file or folder needs no agent.

## Start and Stop

An agent has one switch, in its header: **Start** and **Stop**. It runs everything inside the agent, so its workflows, conversation flows and coworkers have no switch of their own.

| | Start | Stop |
| - | - | - |
| Channels | Rows that answer answer, and rows that start can start | No one answers, and nothing starts |
| Triggers in workflows | Each trigger that is switched on listens: webhooks take calls, schedules fire, app events and file events come in | None listens. A webhook call gets "This agent is stopped" |
| Coworkers' schedules | Fire | Wait. Times they miss are not made up later |
| Coworkers' channels | Read and answer | Don't |
| Endpoints | Take calls from other agents, the API and MCP | Refuse calls: "This endpoint's agent is stopped." |
| Work in progress | — | Runs and coworkers' sessions in progress stop |

**Start runs nothing by itself.** A workflow that has only a Start step waits to be run, by a person, a step, an endpoint or a coworker. A workflow with triggers waits for them. Start asks nothing first.

**Stop asks first.** The dialog, "Stop *agent*?", says what closes and lists the work in progress it stops, such as "Work in progress stops: 2 runs and 1 task". Click **Stop** to confirm.

**To leave one way in out, switch off its row:** a channel in **Settings → Channels**, a trigger or a coworker's schedule in **Settings → Triggers**, an endpoint in **External access**. Never the item. While the agent runs, a row you switch on goes live at once, and a row you switch off stops at once; the rest of the agent carries on.

### What stays on an item

Each item keeps what does it once:

* **A workflow** has **Run**: once, now, asking for its Start inputs. Its row says what wakes it: "Listens: New email (Gmail) · Every weekday 9:00", "Runs when called", "Its triggers are off", or its problem. A Run in a stopped agent does its steps and sets nothing listening.
* **A conversation flow** has **Test**, and says where it talks, such as "Answers on WhatsApp · Website chat". In the flow editor, **Publish** sets the version callers get: it is live at once while the agent runs, and at its next Start while it is stopped. See [Publish a conversation flow](https://docs.cogniagent.ai/conversation-flows/operate/deploy.md).
* **A coworker** has **New session**, and shows its channels and schedules, such as "Slack · 2 schedules". A retired coworker's row reads **Retired · Bring back**. See [Retiring and reusing a coworker](https://docs.cogniagent.ai/cowork/coworkers/templates.md).

### While it is stopped

The header says **Stopped**. Nothing from outside reaches the agent and nothing fires by itself, but you can still build, Run, Test and give coworkers sessions here. You can still talk to it on its page: "Stopped. It answers you here, and does no work on its own until you start it." Its channel, trigger and endpoint rows that are on say **Waits for the agent to start**.

### When something can't start

Start never stops halfway because one part fails. The agent runs, and its header says **Running · 1 problem**. Click it: the **Ways in** card on the agent's home lists the problem first, with what fixes it, such as a Gmail trigger whose account was disconnected. A trigger's problem opens that trigger in **Settings → Triggers**. Switching that row off clears the problem too. Pressing **Start** again checks everything again.

### New agents

A new agent starts stopped, whether you make it or install it, so going live is always your choice. An installed agent's **Finish setup** ends with **Start**.

### Who can start and stop

Whoever may change the agent and may use every item in it. When one item is out of your reach, the message names it.

### Unsorted

Unsorted is a tray, not an agent, so it has no Start or Stop. Its items keep their own switches (a workflow's **Turn on**, a flow's **Undeploy**, a coworker's switch) until you move them into agents.

## Triggers

A trigger starts the agent's work without anyone writing to it: another app calls a webhook, an email arrives, a file lands in a folder, or a schedule is due. It runs one of the agent's workflows, or hands the event to one of its coworkers. Open the agent, click **Settings** in its header, and choose **Triggers**. Settings opens on it.

The rows come in two groups:

* **When something happens**: the webhooks, app events, file events and conversation events of the agent's workflows.
* **On a schedule**: its workflows' schedules and its coworkers' schedules.

Add a trigger here with **Add a trigger**, or in its workflow on the canvas. Either way it shows here as soon as it exists, and you can change it or switch it off from here. Channels, where people talk to the agent, have their own section: see [Channels](https://docs.cogniagent.ai/features/ways-in.md). **Unsorted** has no Triggers.

### Add a trigger

Click **Add a trigger**. A drawer opens at the side of the page with four steps. Each step opens once you pick the one before it.

1. **What starts it.** Pick one:

   * **On a schedule**
   * **When something happens in an app**
   * **When something calls its web address**
   * **When a file is added to a folder**
   * **When a conversation event happens**

   **Change** picks another. When you have already filled something in, it asks first: "Start over with another kind?" Its settings are cleared. What it runs stays.
2. **Its settings.** **Trigger name** comes filled in from what you picked, such as "New email (Gmail)" or "Daily at 09:00". Change it if you like. Below it are the step's own settings, as in the workflow editor: the app and its event, the schedule, the folder, or the conversation flow and its event. A webhook comes secured, with a token you can copy now. Its address shows once it is added.

   A trigger that listens through an account can take it **From variable**. It then listens with the account the variable holds in the agent's current environment. See [Connection variables](https://docs.cogniagent.ai/features/agent-variables.md#use-it-in-a-trigger-or-a-channel).
3. **What it runs.** One tile for each of the agent's workflows. A tile you can't pick is greyed and says "You can view this workflow, not change it."

   Then comes **A new workflow**: "Made with just this trigger, and opened for you to add its steps". Give it a name under the tile. It starts with the trigger's name.

   Below, under **Or hand it to a coworker**, there is one tile for each coworker of the agent, with its name. Pick one to hand each event to that coworker instead of a workflow. See [Hand it to a coworker](#hand-it-to-a-coworker). A coworker tile you can't pick is greyed and says why:

   * **Retired. Bring Ana back on its page to hand it work.**, with **Open Ana** beside it.
   * **A conversation event goes to a workflow for now.**, on every coworker tile, when it starts with **When a conversation event happens**.
   * **No coworkers in Sales yet**, with **Add a coworker**, when the agent has none.
4. **Connect it to**, or **What Ana does with it** when you picked a coworker.

   * **For a workflow**, tick the steps each event should run. The list holds the workflow's steps that can be run, and the steps its Start leads to come first, under "Where its Start leads". Nothing is ticked for you. Each ticked step is connected to the trigger, as if you drew the line on the canvas, and runs with whatever follows it. Those steps read the event as `{{new_lead.body.email}}`, where `new_lead` is the trigger's step ID.
   * **Connect it later in the editor** adds the trigger on its own, switched off, and opens the workflow so you can connect it on the canvas.
   * **For a coworker**, type what it should do with each event, such as "Reply to the sender, then add the lead to the CRM."

   A trigger is not the Start: steps that read the Start's inputs, such as `{{start.email}}`, get nothing from it. When a step you tick reads them, or a step after it does, a warning names those steps: "Greet reads the Start's inputs. This trigger does not fill the Start, so those values are empty when it runs." Change those steps to read the trigger's event, or pick other steps.

The line above **Add** says what it still waits for, such as "Pick what it runs", "Tick the steps it runs, or connect it later" or "Tell Ana what to do with each event". Once nothing is missing, it says what will happen, such as "When something calls its web address, it runs Greet in Lead intake." or "When something calls its web address, Ana gets it as a new session."

Click **Add**. The message says what happened:

* *Added. It listens now.* The agent runs, and the trigger listens.
* *Added. It goes live when the agent starts.* The agent is stopped.
* *Added. It listens once its workflow is on.* Its workflow is switched off.
* *Added, but it could not be set up:* followed by the reason. The row shows the problem, with **Fix**.

When you ticked steps, or picked a coworker, the trigger is switched on and its drawer opens in place, so a webhook's address and token are right there.

With **Connect it later in the editor** or **A new workflow**, the workflow opens in the editor instead, with the new trigger selected. It starts switched off, because it runs nothing yet: *Added, switched off: it runs nothing yet. Connect it to a step, then switch it on with the power button above its card.* A new workflow holds only the trigger, and each event starts a run of its own.

Whoever may change the agent sees **Add a trigger**. To add one to an existing workflow, you also need edit access to that workflow: its tile says so otherwise.

### Hand it to a coworker

Pick a coworker in **What it runs**, and each event becomes work for that coworker: a new session that starts with your instructions, then the event itself.

What the coworker gets after your instructions depends on what starts the trigger:

| What starts it | The coworker also gets |
| - | - |
| **When something calls its web address** | The request's body |
| **When something happens in an app** | The event's details |
| **On a schedule** | The time it fired |
| **When a file is added to a folder** | The files added |

A conversation event can't go to a coworker yet: send it to a workflow.

* **Each event starts a new session** on the coworker's **Sessions** tab, so two calls never mix.
* **The coworker works as you,** the person who added the trigger. Its questions and approvals come to you. The drawer says so: "Runs as you".
* **There is nothing else to manage.** Everything about the trigger, its settings, its coworker, its instructions, its switch, is changed in its drawer here. The agent's home and its workflows don't list anything for it.
* **A webhook answers each call at once.** Its caller gets no result back: the coworker works on it in its session.
* **It listens like any trigger:** at once while the agent runs, or from the next **Start** while it is stopped. A call into a stopped agent is turned away.

A trigger a coworker set up for itself earlier shows the same way. It keeps working as it did, so its events may share one session.

The coworker's **Schedules** tab lists the triggers that hand it work, with **Change it** to open each one here. See [Triggers that hand it work](https://docs.cogniagent.ai/cowork/autonomy/schedules.md#triggers-that-hand-it-work).

**Switching a coworker off, retiring it or deleting it switches off the triggers that hand it work.** The confirm says how many, such as "Its 2 triggers will be switched off.", and the message after it says they were. Bringing the coworker back leaves them off, and the message says so: switch them on again here when you're ready.

A trigger whose coworker can no longer take its events shows the problem on its row:

* *Ana is retired, so this trigger hands work to no one. Bring Ana back, or switch it off.*
* *Its coworker was removed. Remove this trigger, or switch it off.*
* *Ana is now in Support, so its events are refused. Remove this trigger and add it in Support.*

### What it runs

A trigger runs the steps it is connected to in its workflow, like the lines on the canvas show. It is an entry of its own: nothing leads into a Start. Or it hands each event to a coworker: see [Hand it to a coworker](#hand-it-to-a-coworker).

A trigger's drawer has a **What it runs** section:

* **Leads to**, then the steps it is connected to, such as **Greet**. Click one to open it on the canvas. Connections are changed on the canvas.
* **"Not connected to any step yet, so it runs nothing."** with **Connect it in the workflow**, which opens the canvas with the trigger selected.
* **"Hands each event to Ana, as a new session."** with **Open Ana**, for a trigger that hands its events to a coworker. In the drawer, **What Ana does with it** below it holds your instructions: change them and click **Save**. Ana still gets the event after them. A trigger set up to send every event to one session says "Hands each event to Ana, in the same session each time." instead. An older trigger whose workflow runs as one listener says "Hands each event to Ana. While it listens, its events go to one session."

For a coworker's trigger:

* **To hand the events to another coworker,** click **Change** beside Ana, pick the coworker, and click **Save**. The next event goes to the new coworker, with the same instructions. You can pick a coworker the trigger's person can reach; otherwise Save says so, such as "This trigger runs as Dana, who can't reach Bob. Pick a coworker Dana can reach." When the trigger was switched off because Ana was retired, **Switch it on when you save** turns it back on in the same save.
* **Remove trigger** asks first: "Remove this trigger?" "It stops listening, so Ana gets no more events from it. Ana's sessions stay."
* **Moving the coworker** to another agent takes its triggers along.

A trigger's panel in the workflow editor shows **What it runs** only for a trigger that hands its events to a coworker. For any other, the canvas shows what it runs.

**Remove trigger**, at the end of the drawer, deletes the trigger from its workflow. It asks first, such as "Remove New lead?" "New lead is deleted from Lead intake, so calls to its web address stop working. The steps it leads to stay in the workflow." You need edit access to the workflow.

### What a row shows

* **Its name**: the step's name in its workflow. Under it, what it listens to, such as "Webhook · …/a8f3" or "Every Monday at 09:00 (Europe/Kyiv)".
* **What it runs**, such as "Leads to Greet in Lead intake". Click it to open the step in its workflow. A trigger that hands its events to a coworker reads **Hands it to Ana** instead: click it to open Ana's **Schedules** tab. When you can't see that coworker, it reads **Hands it to a coworker**.
* **When it last fired**: "Last fired 3 min ago", or "No fire recorded yet". A busy trigger records at most one fire a minute. An older trigger reads "No fire recorded yet" until it next fires.
* **When it fires next**, for a schedule that is listening: "Next: Fri 09:00 (Europe/Kyiv)", in the schedule's own time zone.
* **Its state**, and a switch.

| State | What it means |
| - | - |
| **Listening** | It is set up and waits for its event or its time |
| **Takes calls** | A webhook that answers calls |
| **Waits for the agent to start** | It is on, and the agent is stopped. It listens as soon as you click **Start** |
| **Off** | It is switched off |
| **Not set up** | Something must be set or fixed first. The row says what, with **Fix**. A switched-on trigger connected to no step says "Runs nothing: connect it to a step." |
| **On** | It is on in a running agent, and has not reported back yet |

A problem shows under the row, with **Fix**, which opens the trigger. A call that was turned away shows as a quiet note instead, such as "Refused a call without its token · 5 min ago". These notes never count as a problem of the agent, so a stranger with a wrong token can't make your agent look broken.

### Switch a trigger on or off

The row's switch is the same switch as the step's own in its workflow:

* **While the agent runs,** a trigger you switch off stops at once: *Switched off. It stops listening.* A trigger you switch on listens at once.
* **While it is stopped,** a trigger you switch on waits for **Start**.

A coworker's schedule has a switch here too. To change its time or its task, open the coworker's **Schedules** tab.

### In each environment

When the agent has more than one [environment](https://docs.cogniagent.ai/features/environments.md), such as Production and Demo, a trigger step is still one step of its workflow, which every environment shares. Its **settings** are per environment: the account it listens with, its filters, a schedule's time, a webhook's token and answer. Production's are the ones on the canvas. Every other environment's are its own copy, changed here.

* **Triggers shows one environment at a time.** Pick it under **Environment**: the one the agent runs in comes first. When it shows another one, a note says: "Demo's trigger settings. They are used while the agent runs in Demo. It runs in Production now." Each row then reads "Not armed while the agent runs in Production" in place of when it last fired.
* **The drawer edits the settings of the environment shown**, and says whose they are: "Demo's settings. Changing them never changes Production's, which are the ones on the canvas." A save there says "Saved. It listens once the agent runs in Demo."
* **Each environment owns its account**, a fixed one or a [Connection variable](https://docs.cogniagent.ai/features/agent-variables.md#use-it-in-a-trigger-or-a-channel). Production's can listen on the real inbox while Demo's listens on a test one.
* **The switch** on another environment's row switches the trigger there only: "Switched off in Demo." On Production's rows it is the step's own switch, as on the canvas.
* **A webhook keeps one address** in every environment. Its token and what it answers are each environment's own.

### A step with no settings in an environment

A step with no settings in Demo does not listen there. Its row on Demo's tab reads **Not in Demo** and opens no drawer. A trigger you add has Production's settings, so it reads **Not in Demo** until you copy it there.

To copy one, open its row's menu and click **Copy to Demo**. It is offered for each environment that has no settings for it yet. The copy is separate: "Demo has its own settings for it now. Changing them never changes this one's." A copy that uses an account you cannot use is made switched off. **Copy to Production** writes the settings onto the canvas.

A coworker's schedule belongs to one environment too, and its menu has **Copy to Demo** here and on the coworker's **Schedules** tab. The copy fires as you, so it asks first. See [Schedules in each environment](https://docs.cogniagent.ai/cowork/autonomy/schedules.md#in-each-environment).

While the agent runs in an environment where a trigger has no settings, or its settings there are switched off:

* It doesn't listen, and a schedule doesn't fire.
* A call to its webhook gets 409 `trigger_not_in_environment`: "This trigger is off in the environment its agent runs in now."
* **Run again** on one of its past events is refused.

Without this, a switch to Demo would fire every Production schedule with Demo's data.

### Change a trigger

Click a row to open it in a drawer at the side of the page. The drawer has the same settings as the step in the workflow editor, with **Step name** on top. Change what you need and click **Save**. **Save** stays off until you change something. **Open in the workflow** opens the step on its canvas, and **Cancel** closes the drawer.

The change is saved into the workflow step, and the trigger is set up again at once. With more than one environment, the drawer saves the settings of the environment it shows: Production's into the step, another's as that environment's own. Only a change in the environment the agent runs in is set up at once; the others wait until the agent runs there. See [In each environment](#in-each-environment). The message says what happened:

* *Saved. It listens on the new settings.* The agent runs, and the trigger listens.
* *Saved. It goes live when the agent starts.* The agent is stopped.
* *Saved. Only its name changed.* Nothing it listens to changed.
* *Saved, but it could not be set up:* followed by the reason, such as a disconnected account. The row shows the problem, with **Fix**.

If someone changes the same step in the workflow while your drawer has unsaved changes, the drawer says "Changed in the workflow since you opened it." Click **Reload** to see their version, which drops your changes, or **Save** to keep yours. Leaving the drawer with unsaved changes asks first.

A webhook with no token says **Open to anyone with the address**, with **Add a token**. See [Keep your webhook secure](https://docs.cogniagent.ai/nodes/triggers/webhook.md#keep-your-webhook-secure).

### Who can change triggers

Whoever may change the agent and edit the workflow. Everyone else who can open the agent sees the rows and the drawer, read-only, and the switch says why: "You can view this workflow, not change it." A step that uses an account you may not use is read-only for you too, and says whose account it is.

## Move items between agents

Moving changes where an item sits. Its id, address, webhooks, phone number, schedule and history stay the same. Whether it works follows its new agent:

* **Into a running agent,** an item that is on stays on. An item that is off has its rows switched off, so nothing wakes up.

* **Into a stopped agent,** an item that is on stops, and the Move dialog says so first, for example "Lead intake stops listening: Billing is stopped."

* **Into Unsorted,** it gets its own switch back, as it is.

* **Drag** an item from a list onto an agent in the sidebar.

* **Move to agent…** in a row's menu moves one item.

* Select several rows and click **Move to agent…** to move them together.

* On Unsorted, select items and click **New agent from selected** to create an agent with them in it. It starts running when any of them was on.

A coworker's sessions move with the coworker. To copy an item instead, use **Duplicate**: the copy stays in the same agent. A copy of a workflow arrives with its triggers switched off, so one event never runs twice, and the message says so: "Its 2 triggers are off: switch them on in the workflow."

An item's channels and [endpoints](https://docs.cogniagent.ai/features/endpoints.md) move with it by default. The Move dialog lets you leave them behind instead, switched off. An endpoint keeps its API address and keys.

In an agent with more than one [environment](https://docs.cogniagent.ai/features/environments.md), only an item's Production channels move, into the new agent's Production. Its channels in other environments stay behind, off, with no one answering, and the Move dialog names them. Only Production's endpoints, trigger settings and schedules move, too. Their copies in other environments are deleted, and the Move dialog names them first: "Other environments' copies of 1 endpoint and 1 trigger's settings are deleted: only Production's move into Billing. Undo does not bring them back." A store that moves takes only its Production files or rows: its own files and rows in the other environments go to the Trash, and the Move dialog says so first. See [Sharing and moving](https://docs.cogniagent.ai/features/environments.md#sharing-and-moving).

Calls between agents need an offer, so a move that would split a caller from what it calls asks first. Choose **Move them together** or **Offer what is called**. See [Move items between agents](https://docs.cogniagent.ai/features/endpoints.md#move-items-between-agents).

You can move only items you can edit. An agent is not a permission: putting an item in an agent you can open gives you nothing more on that item. Sessions stay in workspace agents, not in a project's.

## Files

Your workspace files are still one shared folder, **Workspace files**. Open any agent in the sidebar and click **Files** under it: it opens on the agent's own files, with **Workspace files** and the **Trash** beside them. A file or folder never needs an agent. Files from before agents are in Workspace files too, not in Unsorted.

An agent's own files are the files labelled with it, such as the files that came with an installed copy of a shared agent. What you upload there goes into the agent's folder, named after it, at the top of Workspace files. Each of these files is also in Workspace files, at the same path. Files are shared by all agents: any coworker or workflow, in any agent, reads a file by its path, such as `@files/prices.pdf`. See [An agent's Files](https://docs.cogniagent.ai/cowork/files/files-page.md).

## Data stores

An agent can also hold [data stores](https://docs.cogniagent.ai/features/data-stores.md): **Variable groups** for named values and secrets, a **Database** for records, and **File Stores** for files. Click **Add** on the agent and pick one. Each shows in the sidebar under the agent and on its home.

The agent's own items use its stores. Other agents use one only when you share it with them in the store's **Manage access**, and your app or an AI assistant only with one of the agent's endpoint keys. A store another agent shares with this one shows under **Shared by other agents**, "Pricing · from Front desk". When you move an item to another agent, the move window asks whether to bring along the stores of its agent it uses, and says what becomes of the stores other agents share with it: "Sales will use it too", or that the item will need attention there. Deleting an agent deletes its stores, after a list of what will go, which names the other agents' items that use them; those show it under **Needs attention**. See [Data stores](https://docs.cogniagent.ai/features/data-stores.md#use-a-store-another-agent-shares).

An agent can have more than one [environment](https://docs.cogniagent.ai/features/environments.md), such as Demo next to Production. Each environment has its own variable values, its own rows and files in each Database and File Store that is separate in each environment, and its own [channels](https://docs.cogniagent.ai/features/ways-in.md#in-each-environment), [endpoints](https://docs.cogniagent.ai/features/endpoints.md#in-each-environment), [trigger settings](#in-each-environment) and schedules. See [Agent variables and secrets](https://docs.cogniagent.ai/features/agent-variables.md), [Database](https://docs.cogniagent.ai/features/databases.md), [File Stores](https://docs.cogniagent.ai/features/file-stores.md) and [Agent data API](https://docs.cogniagent.ai/api/stores.md).

## Rename or delete an agent

Use the **⋯** menu beside the agent's name. Deleting an agent deletes everything inside it, after a list of what will go. Sessions that other members started stay theirs: they move or delete them first. Files are kept: they stay in Workspace files, and only the agent's label goes.

You can delete an agent only if you could delete each item in it yourself. Files do not count: they stay in Files. If something in it is someone else's to delete, nothing is deleted and the list says what is in the way. A link made from a deleted agent stops working.

Unsorted cannot be renamed or deleted. It disappears when it is empty.

## Projects

In a workspace that uses projects, each project has its own agents and its own Unsorted. Items move between agents within a project; moving between projects works as before.

## For the API and MCP

Every create call for a workflow, conversation flow, coworker, knowledge base or task names the agent the item goes into, as `agentId`. A create without one is refused with an error that says so. Files and folders need no agent: `write_workspace_file` and `create_workspace_folder` take `agentId` only to label what they create. `list_agents` shows your agents and whether each is running, `manage_agent` creates, renames, starts, stops and deletes them, and `move_to_agent` moves items. See [Start and stop an agent](https://docs.cogniagent.ai/mcp-server.md#start-and-stop-an-agent). Every item you read carries its `agentId`.

`move_to_agent` skips an item whose move would split a call between agents, with `agent.splits_calls` and the pairs it would split. Ask the person, then call it again with `pairs: 'together'` (move the other side too) or `pairs: 'offer'` (offer what is called to every agent). `list_agent_endpoints` lists what agents offer, and `manage_agent_endpoint` creates, changes, switches and deletes endpoints. Endpoint keys are made only in the app. See [Endpoint API](https://docs.cogniagent.ai/api/endpoints.md).

## Common questions

> [accordion] Where did my workflows go?
>
> They are in **Unsorted**, at the bottom of the Agents list, with everything else you built before agents except files. They run as before, with the same addresses, webhooks, schedules and history. The old Workflows page now opens Unsorted, filtered to workflows.

> [accordion] Why is everything in Unsorted?
>
> Nothing you built before agents belonged to one, so it all starts in Unsorted rather than in a guessed agent. Move items into agents whenever you like; there is no deadline. Unsorted disappears when it is empty. Files are not in Unsorted: they stay in Workspace files, which any agent's **Files** opens.

> [accordion] Does moving an item break anything?
>
> No. Moving changes where an item sits: its id, address, webhooks, phone number, schedule and history stay the same. Its endpoints move with it, so callers in other agents still reach it. Whether it works follows its new agent: moving an item that is on into a stopped agent stops it, and the Move dialog says so first. A move that would split a caller from what it calls asks you first.

> [accordion] Can an item use an item in another agent?
>
> Yes, when that agent offers it as an [endpoint](https://docs.cogniagent.ai/features/endpoints.md). A workflow calls it with **Call an agent**, a coworker with its own tool, and an actor with an Execute Workflow tool. Knowledge bases, connections and files need no offer: every agent shares them.

> [accordion] Where did Turn on, Deploy and Pause go?
>
> An agent has one switch: **Start** and **Stop** in its header. Its workflows keep **Run**, its conversation flows **Test** and **Publish**, and its coworkers **New session**. To leave one way in out, switch off its row. Items in **Unsorted** keep their own switches. See [Start and Stop](#start-and-stop).

> [accordion] Can I copy an item into another agent?
>
> Not in one step. Use **Duplicate** to make a copy in the same agent, then move the copy with **Move to agent…**.


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