Platform Quick Tutorial

Complete platform workflow: register, create workspace, project, issues, and assign AI agents in 10 minutes

Set up a complete project management workflow with AI agents in under 10 minutes.

from praisonaiagents import Agent

agent = Agent(
    name="Tutorial Agent",
    instructions="Help complete the platform quick-start workflow.",
)

agent.start("Register my workspace and first issue.")

The user follows each step—register, create a workspace, add issues, assign the agent, and review activity.

Prerequisites: Platform server running on localhost:8000. If you haven’t set up the server yet, see the Getting Started guide.

Tutorial Workflow

1. Register & Login

   Create your user account and obtain an authentication token:

   # Register a new user
   curl -s -X POST http://localhost:8000/api/v1/auth/register \
     -H "Content-Type: application/json" \
     -d '{"email":"[e-mail]","password":"tutorial123","name":"Tutorial User"}' \
     --max-time 10
   

   Expected Response:

   {
     "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
     "user": {
       "id": 1,
       "email": "[e-mail]",
       "name": "Tutorial User"
     }
   }
   

   Save the token for subsequent requests:

   export TOKEN="paste-your-token-here"
   export WS_ID=""  # Will fill in next step
   
2. Create a Workspace

   Create a workspace to organize your projects:

   curl -s -X POST http://localhost:8000/api/v1/workspaces/ \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"name":"Tutorial Workspace","slug":"tutorial"}' \
     --max-time 10
   

   Expected Response:

   {
     "id": "ws_abc123",
     "name": "Tutorial Workspace",
     "slug": "tutorial",
     "created_at": "2024-04-14T09:00:00Z"
   }
   

   Save the workspace ID:

   export WS_ID="ws_abc123"  # Replace with your actual workspace ID
   
3. Create a Project

   Create your first project within the workspace:

   curl -s -X POST http://localhost:8000/api/v1/workspaces/$WS_ID/projects/ \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"title":"My First Project","description":"Learning the platform"}' \
     --max-time 10
   

   Expected Response:

   {
     "id": "proj_xyz789",
     "title": "My First Project",
     "description": "Learning the platform",
     "workspace_id": "ws_abc123",
     "created_at": "2024-04-14T09:01:00Z"
   }
   

   Save the project ID:

   export PROJECT_ID="proj_xyz789"  # Replace with your actual project ID
   
4. Create Issues

   Create three issues with different priorities to demonstrate the workflow:

   High Priority 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": "Fix login bug",
       "description": "Users cannot log in with special characters in password",
       "priority": "high",
       "project_id": "'$PROJECT_ID'"
     }' \
     --max-time 10
   

   Medium Priority 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": "Improve dashboard performance",
       "description": "Dashboard loads slowly with large datasets",
       "priority": "medium",
       "project_id": "'$PROJECT_ID'"
     }' \
     --max-time 10
   

   Low Priority 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": "Update documentation",
       "description": "Add examples to API documentation",
       "priority": "low",
       "project_id": "'$PROJECT_ID'"
     }' \
     --max-time 10
   

   Each issue will receive an auto-generated identifier like ISS-1, ISS-2, ISS-3.

5. Register an AI Agent

   Create an AI agent that can be assigned to issues:

   curl -s -X POST http://localhost:8000/api/v1/workspaces/$WS_ID/agents/ \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "BugFixerBot",
       "instructions": "You are an expert software engineer. Analyze bugs, provide solutions, and write clean code fixes.",
       "model": "gpt-4o",
       "capabilities": ["code_analysis", "bug_fixing", "testing"]
     }' \
     --max-time 10
   

   Expected Response:

   {
     "id": "agent_def456",
     "name": "BugFixerBot",
     "instructions": "You are an expert software engineer...",
     "workspace_id": "ws_abc123",
     "status": "active",
     "created_at": "2024-04-14T09:02:00Z"
   }
   

   Save the agent ID:

   export AGENT_ID="agent_def456"  # Replace with your actual agent ID
   
6. Assign Issue to Agent

   Assign the high-priority login bug to your AI agent:

   # First, get the issue ID for ISS-1
   curl -s "http://localhost:8000/api/v1/workspaces/$WS_ID/issues?project_id=$PROJECT_ID" \
     -H "Authorization: Bearer $TOKEN" \
     --max-time 10
   

   # Assign the issue (replace ISSUE_ID with the actual ID from above)
   export ISSUE_ID="iss_123"  # Replace with actual issue ID
   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
   

   Expected Response:

   {
     "id": "iss_123",
     "title": "Fix login bug",
     "status": "in_progress",
     "assignee_type": "agent",
     "assignee_id": "agent_def456",
     "identifier": "ISS-1"
   }
   
7. Add Comments

   Add comments to demonstrate the conversation flow:

   Agent Analysis Comment:

   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": "I have analyzed the login bug. The issue appears to be with special character encoding in the password validation. I will implement a fix using proper URL encoding.",
       "author_type": "agent",
       "author_id": "'$AGENT_ID'"
     }' \
     --max-time 10
   

   Threaded Reply:

   # Get the comment ID from the previous response, then reply
   export COMMENT_ID="comment_789"  # Replace with actual comment ID
   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": "Fix implemented and tested. Ready for review.",
       "author_type": "agent",
       "author_id": "'$AGENT_ID'",
       "parent_id": "'$COMMENT_ID'"
     }' \
     --max-time 10
   
8. Check Activity Log

   View the activity timeline for your workspace:

   curl -s "http://localhost:8000/api/v1/workspaces/$WS_ID/activity?limit=10" \
     -H "Authorization: Bearer $TOKEN" \
     --max-time 10
   

   Expected Response:

   {
     "activities": [
       {
         "id": "act_001",
         "type": "comment_created",
         "actor_type": "agent",
         "actor_name": "BugFixerBot",
         "target_type": "issue",
         "target_title": "Fix login bug",
         "timestamp": "2024-04-14T09:03:00Z"
       },
       {
         "id": "act_002",
         "type": "issue_assigned",
         "actor_type": "user",
         "actor_name": "Tutorial User",
         "target_type": "issue",
         "target_title": "Fix login bug",
         "timestamp": "2024-04-14T09:02:30Z"
       }
     ]
   }
   
9. View Project Stats

   Check your project statistics to see progress:

   curl -s http://localhost:8000/api/v1/workspaces/$WS_ID/projects/$PROJECT_ID/stats \
     -H "Authorization: Bearer $TOKEN" \
     --max-time 10
   

   Expected Response:

   {
     "total_issues": 3,
     "open_issues": 2,
     "in_progress_issues": 1,
     "completed_issues": 0,
     "total_agents": 1,
     "active_agents": 1,
     "total_comments": 2
   }
   

---

What You Built

Congratulations! You’ve created a complete project management workflow:

Component	What You Created	Auto-Generated ID
User Account	[e-mail]	user_001
Workspace	Tutorial Workspace	ws_abc123
Project	My First Project	proj_xyz789
Issues	3 issues with different priorities	ISS-1, ISS-2, ISS-3
AI Agent	BugFixerBot for code analysis	agent_def456
Assignment	Agent working on high-priority bug	-
Comments	Agent analysis and status updates	-
Activity	Complete audit trail	-

---

Next Steps

Pro Tip: Use the shell variables you exported ($TOKEN, $WS_ID, $PROJECT_ID, etc.) to continue exploring the API without re-typing IDs.

Now that you have a working platform setup, explore these features:

Platform Authentication

Advanced auth patterns and API key management

Issue Management

Advanced issue workflows and automation

Agent Configuration

Customize agent capabilities and behavior

Workspace Management

Multi-workspace and team collaboration

---

Troubleshooting

Authentication errors

Problem: Getting 401 Unauthorized errors

Solution: Check that your token is properly exported and not expired:

echo $TOKEN  # Should show your JWT token
curl -s http://localhost:8000/api/v1/auth/verify \
  -H "Authorization: Bearer $TOKEN"

Server connection issues

Problem: Connection refused or timeout errors

Solution: Ensure the platform server is running:

curl -s http://localhost:8000/health
# Should return: {"status": "healthy"}

Issue assignment failures

Problem: Cannot assign issues to agents

Solution: Verify the agent is active and workspace IDs match:

curl -s http://localhost:8000/api/v1/workspaces/$WS_ID/agents/$AGENT_ID \
  -H "Authorization: Bearer $TOKEN"