Agent Groups

Groups organize agents into a hierarchy for management, monitoring, and policy, and they are available on all plans. Whatever a grouped agent does, Asqav signs the action server-side with its own keys, as a party unaffiliated with the agent's operator, so the record stays verifiable by anyone.

Creating Groups

Create a group with a name and optional description:

bash

# Create a top-level group
curl -X POST https://api.asqav.com/api/v1/agent-groups \
  -H "X-API-Key: sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "production", "description": "Production environment agents"}'

# Response includes the new group's id
{"id": "grp_abc123", "name": "production", "parent_id": null, "agent_count": 0}

# Create a child group under it
curl -X POST https://api.asqav.com/api/v1/agent-groups \
  -H "X-API-Key: sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "payment-agents", "description": "Agents handling payment flows", "parent_id": "grp_abc123"}'

Group Hierarchy

Groups support a parent-child structure up to 5 levels deep. Child groups inherit policies from their parent, making it easy to apply rules across sets of agents. A typical hierarchy might look like:

production - Top-level group
- payment-agents - Handles payments
- data-agents - Handles data processing
  - etl-agents - ETL pipelines
  - analytics-agents - Analytics tasks
staging - Staging environment

The maximum nesting depth is 5 levels. Attempting to create a group deeper than 5 levels returns an error.

Assigning Agents

Add or remove agents from a group:

bash

# Add an agent to a group
curl -X POST https://api.asqav.com/api/v1/agent-groups/grp_abc123/agents/agt_abc123 \
  -H "X-API-Key: sk_live_your_key"

# Group detail lists its agents
curl https://api.asqav.com/api/v1/agent-groups/grp_abc123 \
  -H "X-API-Key: sk_live_your_key"

# Remove an agent from a group
curl -X DELETE https://api.asqav.com/api/v1/agent-groups/grp_abc123/agents/agt_abc123 \
  -H "X-API-Key: sk_live_your_key"

Moving Groups

Reparent a group to change its position in the hierarchy. All child groups and agent assignments move with it.

bash

# Move a group under a new parent
curl -X POST https://api.asqav.com/api/v1/agent-groups/grp_abc123/move \
  -H "X-API-Key: sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"parent_id": "grp_new_parent"}'

# Move a group to top level (no parent)
curl -X POST https://api.asqav.com/api/v1/agent-groups/grp_abc123/move \
  -H "X-API-Key: sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"parent_id": null}'

Listing Groups

bash

# List all groups (flat list; parent_id encodes the hierarchy)
curl https://api.asqav.com/api/v1/agent-groups \
  -H "X-API-Key: sk_live_your_key"

# Response (truncated)
[
  {"id": "grp_abc123", "name": "production", "parent_id": null, "agent_count": 4},
  {"id": "grp_def456", "name": "payment-agents", "parent_id": "grp_abc123", "agent_count": 2}
]

# Get one group with its agents
curl https://api.asqav.com/api/v1/agent-groups/grp_abc123 \
  -H "X-API-Key: sk_live_your_key"

Tip

Groups are useful for applying policies to sets of agents at once. Attach a policy to a group and it automatically applies to all agents in that group and its child groups.