Create a Multi-Agent Task

​

Authentication

1. Click on your Profile Image in the top right corner at cloud.blackbox.ai
2. Click on “BLACKBOX API Token” from the dropdown menu
3. Copy the existing token or click “Generate” if you don’t have one yet

​

Headers

​

Request Parameters

[
  {
    "agent": "claude",
    "model": "blackboxai/anthropic/claude-sonnet-4.5"
  },
  {
    "agent": "blackbox",
    "model": "blackboxai/blackbox-pro"
  },
  {
    "agent": "gemini",
    "model": "gemini-2.0-flash-exp"
  }
]

​

Available Agent Models

​

Claude Agent

{
  "agent": "claude",
  "model": "blackboxai/anthropic/claude-sonnet-4.5" // or claude-sonnet-4, claude-opus-4
}

• blackboxai/anthropic/claude-sonnet-4.5 - Latest Sonnet (Recommended)
• blackboxai/anthropic/claude-sonnet-4 - Sonnet 4
• blackboxai/anthropic/claude-opus-4 - Most capable Claude model

​

BLACKBOX Agent

{
  "agent": "blackbox",
  "model": "blackboxai/blackbox-pro" // or other blackbox models
}

• blackboxai/blackbox-pro - BLACKBOX PRO (Recommended)
• blackboxai/anthropic/claude-sonnet-4.5 - Claude via BLACKBOX
• blackboxai/openai/gpt-5-codex - GPT-5 Codex via BLACKBOX
• blackboxai/anthropic/claude-opus-4 - Claude Opus via BLACKBOX
• blackboxai/x-ai/grok-code-fast-1:free - Grok Code (Free)
• blackboxai/google/gemini-2.5-pro - Gemini via BLACKBOX

​

Codex Agent

{
  "agent": "codex",
  "model": "gpt-5-codex" // or other OpenAI models
}

• gpt-5-codex - GPT-5 Codex (Recommended)
• openai/gpt-5 - GPT-5
• openai/gpt-5-mini - GPT-5 Mini
• openai/gpt-5-nano - GPT-5 Nano
• openai/gpt-4.1 - GPT-4.1

​

Gemini Agent

{
  "agent": "gemini",
  "model": "gemini-2.0-flash-exp" // or other Gemini models
}

• gemini-2.0-flash-exp - Gemini 2.0 Flash (Recommended)
• gemini-2.5-pro - Gemini 2.5 Pro
• gemini-2.5-flash - Gemini 2.5 Flash

​

How Multi-Agent Tasks Work

1. Task Submission: You submit a single task with multiple agent configurations
2. Parallel Execution: Each agent independently processes the task simultaneously
3. Independent Analysis: Each agent analyzes the codebase and creates its own solution
4. Separate Commits: Each agent creates its own commits (if working on a repository)
5. Result Aggregation: All results are tracked in the agentExecutions array
6. Comparison: You can compare approaches, code quality, and results across all agents

​

Response Structure

• selectedAgents: Array of agent configurations used (always present when multi-agent task is created)
• multiLaunch: Initially false, becomes true when agents start executing
• agentExecutions: Initially null, populated when agents start executing. Once populated, contains:
  • agent: The agent type
  • model: The model used
  • status: Current status (pending, in_progress, completed, failed)
  • executionId: Unique identifier for this agent’s execution
  • result: The agent’s output (when completed)
  • commits: Array of commits made by this agent
  • error: Error message (if failed)

curl --location 'https://cloud.blackbox.ai/api/tasks' \
--header 'Authorization: Bearer bb_YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "prompt": "Add README in Mandarin",
    "repoUrl": "https://github.com/<org_name>/<repo_name>.git",
    "selectedBranch": "main",
    "selectedAgents": [
        {
            "agent": "claude",
            "model": "blackboxai/anthropic/claude-sonnet-4.5"
        },
        {
            "agent": "blackbox",
            "model": "blackboxai/blackbox-pro"
        }
    ]
}'

{
  "task": {
    "id": "4GsNQMMsGZpv8x_J9ms6L",
    "userId": "user@gmail.com",
    "teamId": null,
    "prompt": "add readme in mandarin",
    "repoUrl": "https://github.com/<org_name>/<repo_name>.git",
    "selectedAgent": "blackbox",
    "selectedModel": "blackboxai/blackbox-pro",
    "installDependencies": false,
    "maxDuration": 300,
    "keepAlive": false,
    "status": "pending",
    "progress": 0,
    "logs": [],
    "followupMessages": null,
    "checkpoint": null,
    "error": null,
    "selectedBranch": "main",
    "branchName": null,
    "sandboxUrl": null,
    "sandboxId": null,
    "agentSandboxConfig": null,
    "merged": false,
    "prNumber": null,
    "prUrl": null,
    "multiLaunch": false,
    "selectedAgents": [
      {
        "agent": "claude",
        "model": "blackboxai/anthropic/claude-sonnet-4.5"
      },
      {
        "agent": "blackbox",
        "model": "blackboxai/blackbox-pro"
      }
    ],
    "agentExecutions": null,
    "diffAnalysis": null,
    "diffStats": null,
    "cumulativeDiff": null,
    "taskSource": "manual",
    "scheduledTaskId": null,
    "repoInstructions": null,
    "environmentVariables": null,
    "testAccounts": null,
    "autoDeployEnabled": false,
    "deploymentProvider": "vercel",
    "vercelDeploymentSettings": null,
    "gcloudDeploymentSettings": null,
    "deployments": null,
    "lock": null,
    "createdAt": "2025-11-20T20:16:19.489Z",
    "updatedAt": "2025-11-20T20:16:19.489Z",
    "completedAt": null,
    "slackUserId": null,
    "slackTeamId": null,
    "slackChannelId": null,
    "slackMessageTs": null,
    "badge": null,
    "batchId": null,
    "isPublic": false,
    "isEmptyGitUser": false,
    "metaData": null
  }
}

​

Best Practices

​

Agent Selection

{
  "selectedAgents": [
    { "agent": "claude", "model": "blackboxai/anthropic/claude-sonnet-4.5" },  // Great for complex reasoning
    { "agent": "codex", "model": "gpt-5-codex" },                              // Excellent for code generation
    { "agent": "gemini", "model": "gemini-2.0-flash-exp" }                     // Fast and efficient
  ]
}

{
  "selectedAgents": [
    { "agent": "claude", "model": "blackboxai/anthropic/claude-sonnet-4.5" },
    { "agent": "claude", "model": "blackboxai/anthropic/claude-opus-4" }
  ]
}

​

Use Cases

{
  "prompt": "Refactor the authentication module to use dependency injection",
  "selectedAgents": [/* 3-4 different agents */]
}

{
  "prompt": "Implement payment processing with Stripe integration",
  "selectedAgents": [/* 2-3 agents for validation */]
}

{
  "prompt": "Add comprehensive API documentation",
  "selectedAgents": [/* 2-3 agents */]
}

​

Performance Tips

1. Optimal Agent Count: Use 2-3 agents for most tasks, up to 5 for critical comparisons
2. Task Complexity: More complex tasks benefit more from multi-agent approach
3. Resource Awareness: Multi-agent tasks consume more credits and take longer
4. Result Analysis: Focus on comparing approach and quality, not just output
5. Polling Frequency: Check status every 5-10 seconds to avoid rate limits

​

Comparison Metrics

• Code Quality: Readability, maintainability, best practices
• Completeness: Does it fully address the prompt?
• Efficiency: Performance and resource usage
• Error Handling: Robustness and edge case coverage
• Documentation: Code comments and explanations
• Testing: Test coverage and quality
• Consistency: Adherence to project conventions

​

Limitations

• Minimum Agents: At least 2 agents required
• Maximum Agents: Up to 5 agents recommended
• Execution Time: Longer than single-agent tasks
• Credit Usage: Consumes credits for each agent execution
• Conflicts: Agents may create conflicting changes (manual merge may be needed)

​

Related Endpoints

• Create Single Agent Task - Standard single-agent task execution