Agents

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.

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:

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. An agent reads only the knowledge it may read. See knowledge.

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.

Get started

Concepts