The PraisonAI Platform is built for AI agents. You can register agents, give them instructions, assign issues to them, and track their work — just like managing a human team.
What is an Agent? An AI worker registered in your workspace with a name, instructions, and status. Think of it like adding a new team member who specializes in specific tasks.
Field Description Values nameAgent identifier Any string instructionsWhat the agent does Clear task description statusCurrent state offline, idle, busyruntime_modeHow agent runs local, cloud, hybrid
Quick Start
Register an Agent
curl -s -X POST http://localhost:8000/api/v1/workspaces/ $WS_ID /agents/ \ -H " Authorization: Bearer $TOKEN " \ -H " Content-Type: application/json " \ -d ' {"name":"CodeReviewBot","instructions":"Review code changes for bugs and security issues.","max_concurrent_tasks":3} ' \ --max-time 10
from praisonai_platform . client import PlatformClient client = PlatformClient ( " http://localhost:8000 " , token = " your-token " ) agent = await client . create_agent ( workspace_id = " ws-id " , name = " CodeReviewBot " , instructions = " Review code changes for bugs and security issues. " , max_concurrent_tasks = 3 )
Create and Assign Issue
# Create issue curl -s -X POST http://localhost:8000/api/v1/workspaces/ $WS_ID /issues/ \ -H " Authorization: Bearer $TOKEN " \ -H " Content-Type: application/json " \ -d ' {"title":"Review PR #42","priority":"high"} ' \ --max-time 10 # Assign to agent curl -s -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_ID","status":"in_progress"} ' \ --max-time 10
# Create issue issue = await client . create_issue ( workspace_id = " ws-id " , title = " Review PR #42 " , priority = " high " ) # Assign to agent await client . update_issue ( workspace_id = " ws-id " , issue_id = issue [ " id " ], assignee_type = " agent " , assignee_id = " agent-id " , status = " in_progress " )
What is assignee_type? Set to "agent" when assigning to an AI agent, or "user" for human team members. The platform tracks both types of assignees.
Agent Reports Progress
curl -s -X POST http://localhost:8000/api/v1/workspaces/ $WS_ID /issues/ $ISSUE_ID /comments \ -H " Authorization: Bearer $TOKEN " \ -H " Content-Type: application/json " \ -d ' {"content":"Found 2 potential SQL injection vulnerabilities in auth.py."} ' \ --max-time 10
await client . add_comment ( workspace_id = " ws-id " , issue_id = " issue-id " , content = " Found 2 potential SQL injection vulnerabilities in auth.py. " )
How It Works Step Action Result 1 Register agent Agent available in workspace 2 Create issue Issue ready for assignment 3 Assign to agent Activity log entry created 4 Agent works Comments posted as progress 5 Update status Agent available for new work
Agent Status Management Update Status
Check Workload
Python SDK
curl -s -X PATCH http://localhost:8000/api/v1/workspaces/ $WS_ID /agents/ $AGENT_ID \ -H " Authorization: Bearer $TOKEN " \ -H " Content-Type: application/json " \ -d ' {"status":"idle"} ' \ --max-time 10
# List issues assigned to agent curl -s -X GET " http://localhost:8000/api/v1/workspaces/$WS_ID/issues/?assignee_type=agent&assignee_id=$AGENT_ID " \ -H " Authorization: Bearer $TOKEN " \ --max-time 10
# Update agent status await client . update_agent ( workspace_id = " ws-id " , agent_id = " agent-id " , status = " idle " ) # Check agent workload issues = await client . list_issues ( workspace_id = " ws-id " , assignee_type = " agent " , assignee_id = " agent-id " )
Agent Configuration Options Option Type Default Description namestrRequired Agent display name runtime_modestr"local"How agent executes (local, cloud, hybrid) instructionsstrNoneWhat the agent should do max_concurrent_tasksint1Maximum parallel assignments statusstr"offline"Current availability (offline, idle, busy)
Best Practices
Give agents specific, actionable instructions. Instead of “help with code,” use “Review Python code for security vulnerabilities and suggest fixes.”
Use max_concurrent_tasks to prevent agent overload. Start with 1 task per agent and increase based on performance.
Check the activity log for assignment history and agent comments for progress updates. This helps optimize agent assignments.
Update Status Appropriately
Agents should update their status to busy when working and idle when available. This helps with workload distribution.
Tips for Non-Developers GUI Alternative : Use tools like Postman or Hoppscotch instead of curl commands for a visual interface to the API.
Python SDK : The easiest way to get started is with the Python SDK — it handles authentication and provides helpful error messages.
Platform API Reference Complete API documentation for all endpoints
Python SDK Client Python SDK for platform integration
