> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Assign Work to AI Agents

> Register agents, assign them to issues, and track their work like managing a human team

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.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Agent Assignment Flow"
        Register[👤 Register Agent] --> Create[📝 Create Issue]
        Create --> Assign[🎯 Assign to Agent]
        Assign --> Work[🤖 Agent Works]
        Work --> Report[📊 Agent Reports]
    end
    
    classDef register fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef issue fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef work fill:#10B981,stroke:#7C90A0,color:#fff
    classDef report fill:#8B0000,stroke:#7C90A0,color:#fff
    
    class Register register
    class Create,Assign issue
    class Work work
    class Report report
```

## 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                     |
| -------------- | ------------------- | -------------------------- |
| `name`         | Agent identifier    | Any string                 |
| `instructions` | What the agent does | Clear task description     |
| `status`       | Current state       | `offline`, `idle`, `busy`  |
| `runtime_mode` | How agent runs      | `local`, `cloud`, `hybrid` |

***

## Quick Start

<Steps>
  <Step title="Register an Agent">
    <Tabs>
      <Tab title="curl">
        ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        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
        ```
      </Tab>

      <Tab title="Python SDK">
        ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        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
        )
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Create and Assign Issue">
    <Tabs>
      <Tab title="curl">
        ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        # 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
        ```
      </Tab>

      <Tab title="Python SDK">
        ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        # 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"
        )
        ```
      </Tab>
    </Tabs>

    <Note>
      **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.
    </Note>
  </Step>

  <Step title="Agent Reports Progress">
    <Tabs>
      <Tab title="curl">
        ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        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
        ```
      </Tab>

      <Tab title="Python SDK">
        ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        await client.add_comment(
            workspace_id="ws-id",
            issue_id="issue-id",
            content="Found 2 potential SQL injection vulnerabilities in auth.py."
        )
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

***

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Platform
    participant Agent
    
    User->>Platform: Register Agent
    Platform-->>User: Agent Created
    User->>Platform: Create Issue
    Platform-->>User: Issue Created
    User->>Platform: Assign Issue to Agent
    Platform->>Agent: Notify Assignment
    Agent->>Platform: Update Status (busy)
    Agent->>Platform: Post Progress Comments
    Agent->>Platform: Update Status (idle)
    Platform-->>User: Work Complete
```

| 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

<Tabs>
  <Tab title="Update Status">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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
    ```
  </Tab>

  <Tab title="Check Workload">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # 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
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # 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"
    )
    ```
  </Tab>
</Tabs>

***

## Agent Configuration Options

| Option                 | Type  | Default     | Description                                      |
| ---------------------- | ----- | ----------- | ------------------------------------------------ |
| `name`                 | `str` | Required    | Agent display name                               |
| `runtime_mode`         | `str` | `"local"`   | How agent executes (`local`, `cloud`, `hybrid`)  |
| `instructions`         | `str` | `None`      | What the agent should do                         |
| `max_concurrent_tasks` | `int` | `1`         | Maximum parallel assignments                     |
| `status`               | `str` | `"offline"` | Current availability (`offline`, `idle`, `busy`) |

***

## Best Practices

<AccordionGroup>
  <Accordion title="Write Clear Instructions">
    Give agents specific, actionable instructions. Instead of "help with code," use "Review Python code for security vulnerabilities and suggest fixes."
  </Accordion>

  <Accordion title="Monitor Agent Workload">
    Use `max_concurrent_tasks` to prevent agent overload. Start with 1 task per agent and increase based on performance.
  </Accordion>

  <Accordion title="Track Agent Activity">
    Check the activity log for assignment history and agent comments for progress updates. This helps optimize agent assignments.
  </Accordion>

  <Accordion title="Update Status Appropriately">
    Agents should update their status to `busy` when working and `idle` when available. This helps with workload distribution.
  </Accordion>
</AccordionGroup>

***

## Tips for Non-Developers

<Note>
  **GUI Alternative**: Use tools like Postman or Hoppscotch instead of curl commands for a visual interface to the API.
</Note>

<Tip>
  **Python SDK**: The easiest way to get started is with the Python SDK — it handles authentication and provides helpful error messages.
</Tip>

***

## Related

<CardGroup cols={2}>
  <Card title="Platform API Reference" icon="code" href="/docs/api-reference">
    Complete API documentation for all endpoints
  </Card>

  <Card title="Python SDK Client" icon="python" href="/docs/features/platform-python-sdk">
    Python SDK for platform integration
  </Card>
</CardGroup>