Back to API Overview

Agent groups API

Agent groups: which agents work together and who leads them.

7 endpoints

Endpoints

POST
/api/v1/agentGroups/list

List the agent groups. Each: id, name, parentGroupId (set on a sub-group), leadAgentId, members (each agent's id and name). Agents in one group may hand off to and ask each other; a group's Lead may also reach the other groups' Leads.

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/agentGroups/list \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{}'
POST
/api/v1/agentGroups/create

Create an agent group. Params: name (one line, at most 80 characters, unique in the workspace), parentGroupId? (makes it a sub-group; at most 3 levels). Returns { id }. A group gives its agents no tool, connection or right: only who they may talk to.

Parameters

namestringrequired

The group's name: one line, at most 80 characters, unique in the workspace.

parentGroupIdstring

Make it a sub-group of this group (its id); leave it out for a top-level group.

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/agentGroups/create \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example",
  "parentGroupId": "example"
}'
POST
/api/v1/agentGroups/rename

Rename an agent group. Params: groupId, name (one line, unique in the workspace).

Parameters

groupIdstringrequired

The group id

namestringrequired

The group's name: one line, at most 80 characters, unique in the workspace.

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/agentGroups/rename \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "groupId": "example",
  "name": "example"
}'
POST
/api/v1/agentGroups/addAgent

Add an agent to a group. Params: groupId, agentId (aiAgent_listSpecialists). Agents in one group may hand off to and ask each other without a "Can hand off to" entry; each still acts with its own rights. At most 50 agents per group. A person is refused when an agent put in touch holds something they may not use (a tool, connection, power or secret, such as “Use secrets” or “Send email to contacts”); the refusal names the permission and whom to ask.

Parameters

groupIdstringrequired

The group id

agentIdstringrequired

The agent id (aiAgent_listSpecialists)

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/agentGroups/addAgent \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "groupId": "example",
  "agentId": "example"
}'
POST
/api/v1/agentGroups/removeAgent

Take an agent out of a group. Params: groupId, agentId. The agent stays in the workspace; if it was the Lead, the group has no Lead.

Parameters

groupIdstringrequired

The group id

agentIdstringrequired

The agent id

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/agentGroups/removeAgent \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "groupId": "example",
  "agentId": "example"
}'
POST
/api/v1/agentGroups/setLead

Set a group's Lead. Params: groupId, agentId (one of the group's agents, or null for no Lead). Leads may hand off to and ask the other groups' Leads. A person is refused when an agent put in touch holds something they may not use (a tool, connection, power or secret, such as “Use secrets” or “Send email to contacts”); the refusal names the permission and whom to ask.

Parameters

groupIdstringrequired

The group id

agentIdstringnullrequired

The agent to make Lead (one of the group's agents)

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/agentGroups/setLead \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "groupId": "example",
  "agentId": {}
}'
POST
/api/v1/agentGroups/delete

Delete an agent group. Params: groupId. Its agents stay in the workspace; a group with sub-groups can't be deleted until they are. Act only on what the person named or picked.

Parameters

groupIdstringrequired

The group id

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/agentGroups/delete \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "groupId": "example"
}'