Agents API

The Agents API provides core AI operations for multi-agent workflows, including chat interactions, task planning, code generation, testing, version control, and documentation.

Overview

Dispersl agents are specialized AI workers that can:

Coordinate with each other to solve complex problems
Use tools and integrations to perform real-world tasks
Maintain context and memory across interactions
Stream real-time updates via NDJSON responses

Endpoints

Chat Agent

POST /agent/chat

Chat with AI to understand internal codebase insights, task progress and documentation.

Request Body

{
  "prompt": "Explain the authentication flow in this codebase",
  "model": "anthropic/claude-3-sonnet",
  "context": "Optional context about the current task",
  "memory": true,
  "voice": false,
  "task_id": "task_123",
  "knowledge": "Optional knowledge base reference",
  "os": "linux",
  "default_dir": "/workspace",
  "current_dir": "/workspace/src",
  "mcp": {}
}

Response

NDJSON stream with real-time chat responses:

{"status": "processing", "message": "Content chunk", "content": "The authentication flow starts with..."}
{"status": "processing", "message": "Knowledge sources", "knowledge": ["auth_docs", "api_spec"]}
{"status": "complete", "message": "Stream completed", "metadata": {"tokens": 850}}

Plan Agent (Multi-Agent Dispersion)

POST /agent/plan

Distributes a complex task across multiple specialized AI agents following SDLC principles.

Request Body

{
  "prompt": "Build a REST API with authentication and user management",
  "model": "anthropic/claude-3-sonnet",
  "agent_name": "lead_architect",
  "context": "Building a Node.js application",
  "task_id": "task_456",
  "knowledge": "project_requirements",
  "os": "linux",
  "default_dir": "/workspace",
  "current_dir": "/workspace",
  "memory": true
}

Response

NDJSON stream showing task breakdown and agent coordination:

{"status": "processing", "message": "Task analysis", "content": "Breaking down into subtasks..."}
{"status": "processing", "message": "Agent assignment", "content": "Assigning coding agent for API development"}
{"status": "processing", "message": "Agent assignment", "content": "Assigning testing agent for test suite"}
{"status": "complete", "message": "Plan completed", "metadata": {"agents_assigned": 3, "estimated_time": "2h"}}

Code Agent

POST /agent/code

Generates and builds code based on the provided prompt with agentic flow and tool execution.

Request Body

{
  "prompt": "Create a user authentication middleware for Express.js",
  "model": "openai/gpt-4",
  "context": "Express.js REST API project",
  "task_id": "task_789",
  "knowledge": "express_patterns",
  "os": "linux",
  "default_dir": "/workspace",
  "current_dir": "/workspace/src",
  "mcp": {}
}

Available Tools

execute_command: Run CLI commands
list_files: List directory contents
read_file: Read file contents
write_to_file: Create new files
edit_file: Modify existing files

Test Agent

POST /agent/test

Generates and builds tests based on the provided prompt with agentic flow and tool execution.

Request Body

{
  "prompt": "Generate comprehensive tests for the user authentication API",
  "model": "openai/gpt-4",
  "context": "Node.js Express API with Jest testing framework",
  "task_id": "task_101",
  "knowledge": "testing_patterns",
  "os": "linux",
  "default_dir": "/workspace",
  "current_dir": "/workspace/tests"
}

Available Tools

detect_test_frameworks: Scan for test frameworks
write_test_file: Generate test files
execute_command: Run test commands
read_file: Analyze existing code
list_files: Explore project structure

Git Agent

POST /agent/git

Handles Git versioning operations with agentic flow and tool execution.

Request Body

{
  "prompt": "Create a feature branch and commit the new authentication module",
  "model": "deepseek/deepseek-r1",
  "context": "Working on user authentication feature",
  "task_id": "task_202",
  "os": "linux",
  "default_dir": "/workspace",
  "current_dir": "/workspace"
}

Available Tools

setup_branch_environment: Initialize new branches
execute_git_command: Run Git commands
git_status: Check repository status
git_diff: View changes
git_add: Stage changes
git_branch: Manage branches
git_log: View commit history
git_repo_info: Get repository metadata
edit_git_infra_file: Manage CI/CD configs

Documentation Agent

POST /agent/document/repo

Generates end-to-end documentation for a repository with agentic flow and tool execution.

Request Body

{
  "url": "https://github.com/username/repo",
  "branch": "main",
  "model": "google/gemini-pro",
  "team_access": true,
  "task_id": "task_303"
}

Response

NDJSON stream with documentation generation progress and metadata:

{"status": "processing", "message": "Analyzing repository", "content": "Scanning codebase structure..."}
{"status": "processing", "message": "Generating docs", "content": "Creating API documentation..."}
{"status": "complete", "message": "Documentation complete", "metadata": {"tokens": 2500, "filesProcessed": 45}}

Error Responses

All agent endpoints return consistent error responses:

400: Invalid request (missing model, ongoing task, team limit reached)
401: No Bearer token provided
500: Internal server error

Best Practices

Use appropriate models: Different agents work better with different models
Provide context: Include relevant context for better results
Enable memory: Use memory for multi-turn conversations
Monitor tokens: Track token usage in response metadata
Handle streams: Process NDJSON responses incrementally

Overview Models