Praison AI

Platform Agent Management

Register, manage, and assign AI agents within workspaces

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

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

python
from praisonaiagents import Agent

agent = Agent(name="CodeReviewBot", instructions="Review pull requests in this workspace.")
agent.start("Register me as a workspace agent for code review.")

The user registers AI agents in a workspace and assigns them to issues so they can comment automatically.

Diagram
graph LR
    subgraph "Agent Management Flow"
        Register[📝 Register Agent] --> List[📋 List Agents]
        List --> Assign[🔄 Assign to Issue]
        Assign --> Work[🤖 Agent Works]
        Work --> Comment[💬 Create Comment]
    end

    classDef register fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef manage fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff

    class Register register
    class List,Assign manage  
    class Work,Comment result
    classDef agent fill:#8B0000,color:#fff
    classDef tool fill:#189AB4,color:#fff

Quick Start

  1. Register Agent

    Register a new agent in your workspace with basic settings.

    bash
    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.

    bash
    curl "http://localhost:8000/api/v1/workspaces/$WS_ID/agents/?status=idle&limit=10" \
  -H "Authorization: Bearer $TOKEN"

How It Works

Diagram
IssueAgentAPIUserIssueAgentAPIUserRegister AgentAgent CreatedAssign Agent to IssueNotify AssignmentProcess & CommentNotification
ComponentPurposeStatus Options
AgentAI worker in workspaceoffline, idle, busy
Runtime ModeHow agent executeslocal (default)
InstructionsSystem prompt/behaviorCustom text instructions
ConcurrencyMax simultaneous tasks1-100 tasks

Workspace Scoping

All GET / PATCH / DELETE endpoints for agents are scoped to the workspace in the URL. If an agent ID exists but belongs to a different workspace, the API returns 404 Not Found — your auth token never reveals whether the ID exists in another workspace.

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

bash
# 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

bash
# 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

bash
# 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

Agent Naming Convention

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
Concurrency Management

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
Instruction Guidelines

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
Status Monitoring

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

Create Agent

bash
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"}
  }'

Update Agent

bash
curl -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",
    "instructions": "Updated instructions here",
    "max_concurrent_tasks": 5
  }'

List Agents

bash
curl "http://localhost:8000/api/v1/workspaces/$WS_ID/agents/?status=idle&limit=10" \
  -H "Authorization: Bearer $TOKEN"

Response Format

json
{
  "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

python
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:

bash
# 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

Related

Issue Management

Assign agents to issues and track their work

 Workspace Settings

Configure workspace-level agent policies