Managing agents

Agents live at the organization level and are managed from the Agents tab of your organization. Creating and configuring an agent requires organization-admin access.

Create an agent

1. Open your organization and go to the Agents tab.
2. Click New agent and give it a name (for example, ops-bot or oncall-assistant), an optional description, and a color to make it easy to recognize in lists and the activity log.
3. Save. The agent starts in the active state with no access yet, it can't see any queues until you add it to a team.

Each organization can have up to three agents. On self-hosted installs you can change this limit with the AGENTS_MAX_PER_ORGANIZATIONenvironment variable. Agent names must be unique within an organization.

Give an agent team access

An agent gets its permissions the same way a person does, through team membership. Add the agent to a team and pick a role:

1. Open the team you want the agent to operate on.
2. In the Members section, click Add agent and select the agent.
3. Choose a role (guest, operator, regular, manager, or admin) or a custom role defined for your organization.

The agent can now access every queue on that team's connections, limited to the actions its role allows. Add the agent to multiple teams to give it access to more queues, each membership can have a different role.

Which queues an agent can see

An agent can only reach queues on connections that belong to a team it's a member of:

• Team connections are visible to the agent, as long as its role on that team includes View queues.
• Personal connections, the ones in your own workspace that aren't shared with a team, are never visible to agents, whatever the agent's role. Calls that target them fail with Queue is not accessible to agents.

If list_queues comes back empty or is missing a queue, check that:

1. The queue's connection is owned by a team, not by an individual user. Move it to a team or create it there.
2. The agent is a member of that team.
3. The agent's role on that team grants View queues.

TIP

Give an agent the least access it needs. If it only needs to triage and retry failed jobs, an operator role (view + retry + promote) is plenty, it won't be able to delete jobs or queues.

Disable or delete an agent

• Disable an agent to immediately revoke access without deleting it, all of its tokens stop working while it's disabled.
• Delete an agent to remove it and its tokens permanently. Its past activity remains in the audit log for accountability.

Pause vs. remove access

Action	Effect
Disable the agent	All tokens rejected until re-enabled
Remove a token	That specific token stops working
Remove a team membership	Agent loses access to that team's queues
Delete the agent	Agent and all its tokens removed