Skip to content
AI Red vs Blue Arena

Agents API

Agents API

Complete API reference for managing agents in the AI Arena.

Base URL

http://localhost:3001/api/agents

List All Agents

Get a list of all agents.

Request

GET /api/agents

Response

[
  {
    "id": "agent-uuid",
    "name": "Red Team Alpha",
    "type": "red",
    "model": "llama-3.3-70b-versatile",
    "systemPrompt": "You are a red team security researcher...",
    "permissions": ["prompt_manipulation", "sql_injection_testing"],
    "createdAt": "2024-12-14T10:00:00Z",
    "updatedAt": "2024-12-14T10:00:00Z"
  }
]

Get Agent by ID

Get details for a specific agent.

Request

GET /api/agents/:id

Response

{
  "id": "agent-uuid",
  "name": "Red Team Alpha",
  "type": "red",
  "model": "llama-3.3-70b-versatile",
  "systemPrompt": "You are a red team security researcher...",
  "permissions": ["prompt_manipulation", "sql_injection_testing"],
  "createdAt": "2024-12-14T10:00:00Z",
  "updatedAt": "2024-12-14T10:00:00Z"
}

Get Available Models

Get a list of all available LLM models.

Request

GET /api/agents/models

Response

{
  "groq": [
    {
      "id": "llama-3.3-70b-versatile",
      "name": "Llama 3.3 70B Versatile",
      "tier": "powerful",
      "contextWindow": 131072
    }
  ],
  "openai": [
    {
      "id": "gpt-4",
      "name": "GPT-4",
      "tier": "powerful"
    }
  ],
  "anthropic": [
    {
      "id": "claude-3-opus",
      "name": "Claude 3 Opus",
      "tier": "powerful"
    }
  ]
}

Create Agent

Create a new agent.

Request

POST /api/agents
Content-Type: application/json
{
  "name": "Red Team Alpha",
  "type": "red",
  "model": "llama-3.3-70b-versatile",
  "systemPrompt": "You are a red team security researcher...",
  "permissions": [
    "prompt_manipulation",
    "sql_injection_testing",
    "http_request"
  ]
}

Agent Types

  • red - Attack agent
  • blue - Defense agent
  • target - Target agent under test

Permissions

Available permissions:

  • http_request - Make HTTP requests
  • prompt_manipulation - Craft prompt injections
  • sql_injection_testing - Test SQL injection
  • code_execution - Execute code in sandbox
  • input_sanitization - Sanitize inputs
  • context_monitoring - Monitor context
  • instruction_enforcement - Enforce instructions
  • file_operations - File operations
  • network_access - Network access
  • tool_execution - General tool execution

Response

{
  "id": "agent-uuid",
  "name": "Red Team Alpha",
  "type": "red",
  "model": "llama-3.3-70b-versatile",
  "systemPrompt": "You are a red team security researcher...",
  "permissions": ["prompt_manipulation", "sql_injection_testing"],
  "createdAt": "2024-12-14T10:00:00Z",
  "updatedAt": "2024-12-14T10:00:00Z"
}

Update Agent

Update an existing agent.

Request

PATCH /api/agents/:id
Content-Type: application/json
{
  "name": "Updated Name",
  "systemPrompt": "Updated system prompt...",
  "permissions": ["new_permission"]
}

Response

{
  "id": "agent-uuid",
  "name": "Updated Name",
  "type": "red",
  "model": "llama-3.3-70b-versatile",
  "systemPrompt": "Updated system prompt...",
  "permissions": ["new_permission"],
  "createdAt": "2024-12-14T10:00:00Z",
  "updatedAt": "2024-12-14T10:30:00Z"
}

Delete Agent

Delete an agent.

Request

DELETE /api/agents/:id

Response

{
  "success": true,
  "message": "Agent deleted"
}

Error Responses

400 Bad Request

{
  "error": "Validation error",
  "details": {
    "field": "model",
    "message": "Invalid model ID"
  }
}

404 Not Found

{
  "error": "Agent not found",
  "id": "agent-uuid"
}

500 Internal Server Error

{
  "error": "Internal server error",
  "message": "Database connection failed"
}

Examples

Create Red Agent

Terminal window
curl -X POST http://localhost:3001/api/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Red Team Alpha",
    "type": "red",
    "model": "llama-3.3-70b-versatile",
    "systemPrompt": "You are a red team security researcher...",
    "permissions": ["prompt_manipulation", "sql_injection_testing"]
  }'

Create Blue Agent

Terminal window
curl -X POST http://localhost:3001/api/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Blue Team Defender",
    "type": "blue",
    "model": "mixtral-8x7b-32768",
    "systemPrompt": "You are a blue team defender...",
    "permissions": ["input_sanitization", "context_monitoring"]
  }'

List All Agents

Terminal window
curl http://localhost:3001/api/agents

Get Available Models

Terminal window
curl http://localhost:3001/api/agents/models

Next Steps