Skip to main content

​
Work Orders

Work orders are requests for AgentGate to perform automated tasks. Each work order specifies what to do, where to do it, and how to handle the results.

​
What Is a Work Order

A work order is your instruction to AgentGate. Think of it like a detailed task assignment:
  • Task Prompt: What you want accomplished
  • Workspace Source: Where to do the work
  • Configuration: How to customize behavior
  • Tenant Context: Who this is for (in B2B2C scenarios)
When you submit a work order, AgentGate creates a run to execute it.

​
Work Order Components

​
Task Prompt

The task prompt describes what you want AgentGate to accomplish. This is the most important part of your work order. 
{
  "taskPrompt": "Add comprehensive error handling to the API routes in src/routes/. Each route should catch errors, log them appropriately, and return standardized error responses."
}
Be specific and provide context. Good prompts include: what to do, where to do it, constraints to follow, and expected outcomes.
Effective prompts include:
  • Clear description of the task
  • Specific files or areas to focus on
  • Coding standards or patterns to follow
  • Expected outcome or acceptance criteria

​
Workspace Source

The workspace source defines where AgentGate should perform the work:
Clone from a Git repository:
{
  "workspaceSource": {
    "type": "git",
    "repository": "https://github.com/your-org/your-repo",
    "branch": "main"
  }
}

​
Configuration Options

Customize how your work order executes:
OptionTypeDescription
maxIterationsnumberMaximum iteration attempts (default: 10)
gatePlanstringVerification level configuration
webhookUrlstringURL for completion notification
metadataobjectCustom key-value data
{
  "taskPrompt": "...",
  "workspaceSource": { "..." },
  "maxIterations": 5,
  "webhookUrl": "https://your-app.com/webhooks/agentgate",
  "metadata": {
    "ticketId": "PROJ-123",
    "priority": "high"
  }
}

​
Work Order Lifecycle

1

Submission

You submit the work order via API. AgentGate validates the request.
2

Validation

AgentGate checks the workspace source is accessible and the request is well-formed.
3

Queuing

A run is created and queued for execution.
4

Execution

The run executes, iterating until completion or limit reached.
5

Completion

Results are available and webhooks are fired.

​
Response Structure

When you create a work order, you receive: 
{
  "workOrderId": "wo_abc123xyz",
  "runId": "run_def456uvw",
  "status": "pending",
  "createdAt": "2024-01-15T10:30:00Z"
}
FieldDescription
workOrderIdUnique identifier for the work order
runIdUnique identifier for the created run
statusInitial status (always pending)
createdAtTimestamp of creation

​
Best Practices

​
Writing Effective Task Prompts

Instead of “fix the bug”, say “fix the null pointer exception in UserService.getUser() that occurs when the user ID doesn’t exist in the database”.
Include relevant background: “This is a Node.js Express API using TypeScript. We follow the repository pattern for data access.”
State what success looks like: “The function should return an empty array instead of throwing an error when no results are found.”
Mention limitations: “Do not modify the database schema. Use existing utility functions where available.”

​
Choosing Workspace Sources

  • Git repositories: Best for existing projects with history
  • Templates: Best for new projects or standardized setups
  • URLs: Best for one-off tasks or external sources

Runs

Learn about run lifecycle and monitoring

API Reference

Create Work Order endpoint