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

# Agents

> What an agent is, who owns it and who can use or edit it.

An agent is a worker with instructions, a tone, a model, tools and knowledge. You make agents, test them, publish them and share them through the [agents API](https://docs.impellabs.tech/api/agents.md).

## Kinds

| Kind | Who owns it |
| - | - |
| `chief_of_staff` | One member. Made for each member when they join. Only that member sees it. |
| `personal` | One member. |
| `department` | A department. |
| `company` | The workspace. Only an owner or an admin makes one. |

Your Chief of Staff is your private assistant. It is not the agent that answers customers. Customer-facing work is done by the agents you make. A member can make as many as they need. A Chief of Staff cannot be paused or archived.

An agent also has a type. `communication` agents answer customers. `prospecting` agents research companies. The type is fixed after the agent was published. Read the types you can choose from `GET /api/v1/agents/types`.

## Versions

Each edit of instructions, tone, model or tools makes a new fixed version. Publishing moves the live pointer to the newest version.

* `live_version` is the version customers talk to.
* `latest_version` is the newest one.
* `unpublished_changes` is `true` when they differ.

A version must be tested in the test chat before you publish it. Publish with `POST /api/v1/agents/{agent_id}/publish`. Pause with `POST /api/v1/agents/{agent_id}/pause`. Only a live agent can be paused. You can restore an earlier version as a new draft.

## Who can use or edit an agent

An agent is private to its owner until the owner shares it, like a document.

| Level | What it allows |
| - | - |
| Owner | Everything. |
| Can edit | Read, change, publish and restore. |
| Can use | Read the agent, try it in the test chat and see its versions. |

The owner chooses who gets which level. Share with chosen members, with departments, or with everyone:

```bash theme={null}
curl -X PATCH https://api.impellabs.tech/api/v1/agents/AGENT_ID/sharing \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sharing": {"mode": "people", "members": {"MEMBER_ID": "use"}, "departments": {"DEPARTMENT_ID": "edit"}}}'
```

`mode` is `private`, `people` or `everyone`. For mode `everyone`, `everyone` is `use` or `edit`. Each id must be a valid id and each level `use` or `edit`.

## What owners and admins see

Owners and admins have oversight of agents they do not own. They see the name, owner, kind, status, sharing mode and spend. They never see the content. They have no edit access by role.

By oversight they can also pause an agent, archive it, transfer it to another member or make it private. Each of these is recorded and the agent's owner is told.

`GET /api/v1/agents/oversight` lists every agent except Chiefs of Staff. It needs the capability `agents.edit` at workspace scope, which owners and admins hold.

## Where an agent answers

An agent answers on the channels bound to it. One agent answers on each channel. See [channels](https://docs.impellabs.tech/guides/channels.md).

An agent reads only the knowledge it may read. See [knowledge](https://docs.impellabs.tech/guides/knowledge.md).

## Reply behavior

Three settings change how an agent behaves when a person writes on a conversation. They take effect at once and do not make a version.

| Field | Meaning |
| - | - |
| `pause_when_member_replies` | A reply from a member pauses the agent on that conversation. |
| `resume_after_minutes` | The agent answers again when the customer waits this long. `0` means never. Choices: 0, 5, 10, 15, 30, 60, 120. |
| `notify_when_unsure` | When the agent cannot answer, the member who last had the conversation is told. |


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