Workflow: Creating an Agent Task

Overview

This guide walks you through creating a task that will be executed by an AI agent. You'll learn how to properly configure a task, provide clear instructions, and set up the workflow for optimal agent performance.

Time Required: ~10 minutes Skill Level: Beginner

Prerequisites

Before creating an agent task, ensure you have:

• Access to the Agents App
• At least one codebase configured (see Getting Started)
• Understanding of what you want the agent to accomplish
• Clear, specific requirements for the task

Workflow Diagram

+------------------+     +------------------+     +------------------+
|  Define Task     |---->|  Create Task     |---->|  Agent Picks Up  |
|  Requirements    |     |  in App          |     |  Task            |
+------------------+     +------------------+     +------------------+
                                                         |
                                                         v
+------------------+     +------------------+     +------------------+
|  Review Output   |<----|  Approval        |<----|  Agent Executes  |
|  & Iterate       |     |  Created         |     |  Work            |
+------------------+     +------------------+     +------------------+

Steps

Step 1: Define Your Task Requirements

Before opening the app, clearly define what you want the agent to accomplish.

Good task descriptions include:

Bad task descriptions:

• "Fix the code" (too vague)
• "Make it better" (no clear objective)
• "Add some tests" (not specific enough)

Step 2: Open the Task Creation Dialog

1. Navigate to the Dashboard or Tasks page
2. Click the New Task button
3. The task creation dialog will appear

Step 3: Fill in Task Details

Complete the task creation form with clear, actionable information:

Title Field:

• Keep it concise but descriptive
• Use action verbs (Add, Fix, Update, Create, Implement)
• Include the component or area affected

Good: "Add email validation to RegistrationForm"
Bad:  "Registration stuff"

Description Field: Write a detailed description that includes:

1. Context: What is the current state?
2. Objective: What should change?
3. Details: Specific requirements or constraints
4. Acceptance Criteria: How to verify completion

Example description:

## Context
The RegistrationForm component currently accepts any input without validation.
Users can submit empty forms or invalid email addresses.

## Objective
Add client-side validation to all form fields using Zod schemas.

## Requirements
- Email field: validate format using Zod email()
- Password field: minimum 8 characters, at least one number
- Username field: 3-20 characters, alphanumeric only

## Acceptance Criteria
- [ ] Validation errors appear on blur
- [ ] Submit button disabled when form invalid
- [ ] Error messages are user-friendly
- [ ] Existing tests still pass

Step 4: Submit the Task

1. Review your task details for clarity
2. Click Create to submit the task
3. You'll be navigated to the task detail page

The task is now in the queue with status To Do.

Step 5: Monitor Task Progress

Once an agent picks up your task:

1. Task status changes to In Progress
2. Navigate to the task detail page to monitor
3. Check the Activity or Logs tab for real-time updates

Step 6: Respond to Agent Queries

Agents may need clarification. If the agent has questions:

1. Check the Conversation tab on the task detail page
2. Read the agent's query carefully
3. Provide a clear, specific response
4. Click Send to submit your response

The task will be re-queued and the agent will continue with your input.

Step 7: Review the Output

When the agent completes the task:

1. An approval request may be created (if configured)
2. Navigate to Approvals or check the task detail
3. Review the agent's work:
   • Check the output description
   • Review any code changes
   • Verify acceptance criteria are met

Step 8: Take Approval Action

After reviewing, take one of these actions:

Include helpful comments with your decision:

Approve: "Good implementation. Code is clean and tests pass."

Request Revision: "Validation works but error messages need to be
more user-friendly. For example, 'Invalid email' should be
'Please enter a valid email address'."

Expected Results

After completing this workflow, you should see:

• A completed task with status Complete
• Approval status showing Approved (if applicable)
• Agent's work integrated or ready for integration
• Logs showing the execution history

Best Practices

Writing Effective Task Descriptions

1. Be specific: Include file paths, function names, component names
2. Provide context: Explain why the change is needed
3. Set boundaries: Specify what NOT to change
4. Include examples: Show expected input/output if relevant

Task Sizing

For best results, break large tasks into smaller, focused tasks.

Monitoring Tips

1. Check logs regularly: They show detailed execution steps
2. Respond quickly: Pending queries block task progress
3. Review thoroughly: Catch issues early in the approval step

Troubleshooting

Issue: Task stays in "To Do" indefinitely

Cause: No workers available to pick up the task.

Solution:

1. Check the Workers page for active workers
2. Verify workers are configured for your workspace
3. Contact your administrator if no workers are available

Issue: Agent produces incorrect output

Cause: Task description may be unclear or missing context.

Solution:

1. Request revision with specific feedback
2. Provide additional context in your feedback
3. Consider breaking the task into smaller pieces
4. Add explicit acceptance criteria to future tasks

Issue: Agent keeps asking questions

Cause: Task scope may be too broad or ambiguous.

Solution:

1. Answer questions with specific details
2. Consider revising the original task description
3. Break complex tasks into simpler sub-tasks

Related Workflows

• Getting Started - Initial setup guide
• Features - All available features
• Troubleshooting - Common issues and solutions

Summary

Creating effective agent tasks requires:

1. Clear, specific task descriptions
2. Proper context and constraints
3. Measurable acceptance criteria
4. Active monitoring and timely responses
5. Thorough review of agent output

Following these practices leads to better agent performance and higher quality outputs.