Agent groups API
Agent groups: which agents work together and who leads them.
Endpoints
/api/v1/agentGroups/listList 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 '{}'/api/v1/agentGroups/createCreate 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
name | stringrequired | The group's name: one line, at most 80 characters, unique in the workspace. |
parentGroupId | string | 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"
}'/api/v1/agentGroups/renameRename an agent group. Params: groupId, name (one line, unique in the workspace).
Parameters
groupId | stringrequired | The group id |
name | stringrequired | 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"
}'/api/v1/agentGroups/addAgentAdd 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
groupId | stringrequired | The group id |
agentId | stringrequired | 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"
}'/api/v1/agentGroups/removeAgentTake 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
groupId | stringrequired | The group id |
agentId | stringrequired | 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"
}'/api/v1/agentGroups/setLeadSet 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
groupId | stringrequired | The group id |
agentId | stringnullrequired | 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": {}
}'/api/v1/agentGroups/deleteDelete 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
groupId | stringrequired | 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"
}'