Skip to main content
Platform agents are AI workers registered in a workspace that can be assigned to issues and create comments automatically.

​
Quick Start

1

Register Agent

Register a new agent in your workspace with basic settings.
curl -X POST http://localhost:8000/api/v1/workspaces/$WS_ID/agents/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CodeReviewBot",
    "runtime_mode": "local",
    "instructions": "Review all PRs for security issues.",
    "max_concurrent_tasks": 3
  }'
2

List Your Agents

View all agents in your workspace with filtering options.
curl "http://localhost:8000/api/v1/workspaces/$WS_ID/agents/?status=idle&limit=10" \
  -H "Authorization: Bearer $TOKEN"

​
How It Works

ComponentPurposeStatus Options
AgentAI worker in workspaceoffline, idle, busy
Runtime ModeHow agent executeslocal (default)
InstructionsSystem prompt/behaviorCustom text instructions
ConcurrencyMax simultaneous tasks1-100 tasks

​
Configuration Options

​
Agent Properties

PropertyTypeDefaultDescription
namestringrequiredAgent display name
runtime_modestring"local"How the agent runs
instructionsstring""System prompt for agent behavior
max_concurrent_tasksint1Maximum simultaneous tasks (1-100)
runtime_configobject{}Agent-specific settings (model, temperature)
statusstring"offline"Current agent status

​
Status Values

StatusDescription
offlineAgent is not available (default for new agents)
idleAgent is available and ready to work
busyAgent is currently working on tasks

​
Common Patterns

​
Basic Agent Registration

# Register with minimal configuration
curl -X POST http://localhost:8000/api/v1/workspaces/$WS_ID/agents/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "BasicBot",
    "instructions": "Help with general tasks"
  }'

​
Advanced Agent with Custom Configuration

# Register with runtime configuration
curl -X POST http://localhost:8000/api/v1/workspaces/$WS_ID/agents/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AdvancedBot", 
    "runtime_mode": "local",
    "instructions": "Advanced code review with security focus",
    "max_concurrent_tasks": 5,
    "runtime_config": {
      "model": "gpt-4o",
      "temperature": 0.1,
      "max_tokens": 2000
    }
  }'

​
Assigning Agent to Issue

# Update issue to assign agent
curl -X PATCH http://localhost:8000/api/v1/workspaces/$WS_ID/issues/$ISSUE_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assignee_type": "agent",
    "assignee_id": "agent-abc123"
  }'

​
Best Practices

Use descriptive names that indicate the agent’s purpose:
  • CodeReviewBot for code review tasks
  • DocumentationAssistant for documentation help
  • SecurityAuditor for security-focused reviews
  • TestingAgent for automated testing tasks
Set appropriate concurrency limits based on agent capabilities:
  • 1-2 tasks: For complex, resource-intensive work
  • 3-5 tasks: For moderate complexity tasks
  • 5-10 tasks: For simple, quick tasks only
  • Monitor agent performance and adjust limits accordingly
Write clear, specific instructions for consistent behavior:
  • Define the agent’s role and responsibilities
  • Specify output format preferences
  • Include quality standards and criteria
  • Mention any tools or resources the agent should use
Regularly monitor and update agent status:
  • Set to idle when agent should accept new tasks
  • Monitor for agents stuck in busy status
  • Use offline for maintenance or when agent shouldn’t work
  • Check agent performance metrics regularly

​
API Reference

​
Endpoints

MethodPathDescription
POST/api/v1/workspaces/{ws_id}/agents/Register new agent
GET/api/v1/workspaces/{ws_id}/agents/List agents with filters
GET/api/v1/workspaces/{ws_id}/agents/{agent_id}Get specific agent
PATCH/api/v1/workspaces/{ws_id}/agents/{agent_id}Update agent
DELETE/api/v1/workspaces/{ws_id}/agents/{agent_id}Delete agent

​
Query Parameters

ParameterTypeDescription
statusstringFilter by status: offline, idle, busy
limitintMax results (1-200, default: 50)
offsetintSkip N results (default: 0)

​
Request Examples

curl -X POST http://localhost:8000/api/v1/workspaces/$WS_ID/agents/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CodeReviewBot",
    "runtime_mode": "local", 
    "instructions": "Review PRs for security issues.",
    "max_concurrent_tasks": 3,
    "runtime_config": {"model": "gpt-4o"}
  }'

​
Response Format

{
  "id": "agent-abc123",
  "workspace_id": "ws-abc123", 
  "name": "CodeReviewBot",
  "avatar_url": null,
  "runtime_mode": "local",
  "instructions": "Review all PRs for security issues.",
  "status": "offline",
  "max_concurrent_tasks": 3,
  "runtime_config": {"model": "gpt-4o"},
  "owner_id": "user-abc123",
  "created_at": "2025-01-01T00:00:00"
}

​
Python SDK Usage

import asyncio
from praisonai_platform.client import PlatformClient

async def main():
    client = PlatformClient("http://localhost:8000", token="your-jwt-token")
    ws_id = "your-workspace-id"

    # Register agent
    agent = await client.create_agent(
        ws_id, "CodeReviewBot",
        runtime_mode="local",
        instructions="Review PRs for security issues.",
        max_concurrent_tasks=3
    )
    print(f"Created agent: {agent['id']} with status: {agent['status']}")

    # List agents
    agents = await client.list_agents(ws_id, status="idle")
    for agent in agents:
        print(f"Agent: {agent['name']} - Status: {agent['status']}")

    # Get specific agent
    agent_details = await client.get_agent(ws_id, agent["id"])
    
    # Update agent
    updated = await client.update_agent(
        ws_id, agent["id"],
        status="idle",
        instructions="New instructions"
    )
    
    # Delete agent when no longer needed
    await client.delete_agent(ws_id, agent["id"])

asyncio.run(main())

​
Testing

Run these tests to verify agent management functionality: 
# Test agent service
pytest tests/test_new_gaps.py::TestAgentService -v

# Test agent instructions
pytest tests/test_new_gaps.py::TestAgentInstructions -v

# Test agent API routes  
pytest tests/test_new_api_integration.py::TestAgentRoutes -v

Issue Management

Assign agents to issues and track their work

Workspace Settings

Configure workspace-level agent policies