What are Agent-Group Associations?

Agent-group associations control which groups can access specific agents or VTAs in CampusMindAI. By associating agents with groups, you manage access permissions efficiently.

Why Use Agent-Group Associations?

• Access Control: Grant agent access to specific user groups

• Course Management: Assign VTAs to course groups

• Role-Based Access: Control who can use which agents

• Scalable Permissions: Manage access for multiple users at once

Add Group to Agent

Associate one or more groups with an agent, granting group members access.

Endpoint Details

• Method: POST

• URL: {{baseURL}}/api/v1/add_agent_to_group

• Authentication: Required (JWT Bearer token)

Request Body

Example Request

curl -X POST "https://<baseURL>/api/v1/add_agent_to_group" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "group_ids": [1000220],
    "agent_type": "my_agent",
    "agent_name": "Research Assistant",
    "agent_id": "asst_3vqt5pwbDH5iTwoyISDuQgw9",
    "role_id": 2
  }'

Response

Status Code: 200 OK

{
  "agent_id": "asst_3vqt5pwbDH5iTwoyISDuQgw9"
}

Remove Group from Agent

Remove group access from an agent.

Endpoint Details

• Method: POST

• URL: {{baseURL}}/api/v1/remove_agent_from_group

• Authentication: Required (JWT Bearer token)

Request Body

Example Request

curl -X POST "https://<baseURL>/api/v1/remove_agent_from_group" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "group_ids": [1000220],
    "agent_type": "my_agent",
    "agent_id": "asst_3vqt5pwbDH5iTwoyISDuQgw9",
    "agent_name": "Research Assistant"
  }'

Response

Status Code: 200 OK

{
  "agent_id": ""
}

Note: Empty agent_id indicates successful removal.

Common Use Cases

Grant Course Access to VTA

curl -X POST "https://<baseURL>/api/v1/add_agent_to_group" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "group_ids": [1000385],
    "agent_type": "vta",
    "agent_name": "CS101_VTA",
    "agent_id": "asst_XN5v91U6aVRS0r0pJHc6zN18",
    "role_id": 1
  }'

Share Agent with Multiple Groups

curl -X POST "https://<baseURL>/api/v1/add_agent_to_group" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "group_ids": [1000385, 1000386, 1000387],
    "agent_type": "my_agent",
    "agent_name": "Department Assistant",
    "agent_id": "asst_abc123",
    "role_id": 2
  }'

Revoke Group Access

curl -X POST "https://<baseURL>/api/v1/remove_agent_from_group" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "group_ids": [1000385],
    "agent_type": "vta",
    "agent_id": "asst_XN5v91U6aVRS0r0pJHc6zN18",
    "agent_name": "CS101_VTA"
  }'

Agent Types

VTA (Virtual Teaching Assistant)

{
  "agent_type": "vta",
  "agent_id": "asst_XN5v91U6aVRS0r0pJHc6zN18"
}

Custom Agent

{
  "agent_type": "my_agent",
  "agent_id": "asst_3vqt5pwbDH5iTwoyISDuQgw9"
}

Role-Based Access

The role_id parameter defines the access level:

Workflow

Step 1: Create Group

Create a group for the course or department:

curl -X POST "https://<baseURL>/api/v1/create_group/" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "group_name": "CS101_Students",
    "group_description": "CS101 Student Group",
    "global_group": 0,
    "role_id": 1
  }'

Step 2: Add Users to Group

curl -X POST "https://<baseURL>/api/v1/add_users_to_group" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": ["student1@example.com", "student2@example.com"],
    "group_ids": [1000385]
  }'

Step 3: Associate Agent with Group

curl -X POST "https://<baseURL>/api/v1/add_agent_to_group" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "group_ids": [1000385],
    "agent_type": "vta",
    "agent_name": "CS101_VTA",
    "agent_id": "asst_XN5v91U6aVRS0r0pJHc6zN18",
    "role_id": 1
  }'

Error Responses

Best Practices

• Group First: Create groups and add users before associating agents

• Verify IDs: Confirm group IDs and agent IDs are correct

• Role Alignment: Match role_id with group's role

• Bulk Operations: Associate multiple groups at once when possible

• Regular Audits: Review agent-group associations periodically

Troubleshooting

Association Fails

Causes:

• Invalid group ID

• Invalid agent ID

• Agent doesn't exist

• Insufficient permissions

Solutions:

1. Verify group exists using list_group

2. Verify agent exists using list_agents

3. Check your user role has permission

4. Confirm agent_id format is correct

Access Not Working

Causes:

• Users not in the group

• Agent not active

• Association not completed

Solutions:

1. Verify users are in group using list_group_users

2. Check agent status in list_agents

3. Re-associate agent with group