Skip to main content

​
Best Practices

Follow these guidelines to get the best results from AgentGate.

​
Task Prompt Engineering

The task prompt is the most important factor in run success.

​
Be Specific

Add input validation to the createUser function in src/services/user.ts.
Validate that email is a valid email format and password is at least 8
characters. Return appropriate error messages for invalid inputs.

​
Provide Context

Include relevant background information: 
This is a Node.js Express API using TypeScript. We use Zod for validation
and follow the repository pattern. Error responses should use our standard
ApiError class from src/utils/errors.ts.

​
Define Acceptance Criteria

State what success looks like: 
The function should:
1. Return early with a 400 error if email format is invalid
2. Return early with a 400 error if password is under 8 characters
3. Include specific error messages indicating which field failed
4. Add unit tests covering both valid and invalid inputs

​
Specify Constraints

Mention what to avoid: 
Do not modify the database schema. Do not change the function signature.
Use existing utility functions from src/utils where applicable.

​
Workspace Optimization

​
Keep Repositories Focused

Large repositories take longer to clone and may hit size limits. Consider:
  • Using sparse checkout for monorepos
  • Excluding large binaries
  • Removing unnecessary history
If you frequently start from scratch, create organization templates with:
  • Standard project structure
  • Common dependencies pre-installed
  • Build and test configuration

​
Ensure Reproducibility

  • Use lock files: package-lock.json, poetry.lock, etc.
  • Pin versions: Avoid latest tags in dependencies
  • Document environment: Include required environment variables

​
Configure for Automation

Ensure your workspace works without human interaction:
  • Tests run headlessly (no browser popups)
  • Builds complete without prompts
  • No required user input during setup

​
Cost Optimization

​
Right-Size Iteration Limits

Task TypeSuggested Limit
Simple changes3-5 iterations
Medium complexity5-10 iterations
Complex refactors10-15 iterations
{
  "taskPrompt": "Fix typo in error message",
  "maxIterations": 3
}

​
Use Appropriate Verification

Match verification level to task needs:
  • Quick prototypes: L0 only
  • Bug fixes: L0 + L1
  • Production features: All levels

​
Break Down Complex Tasks

Instead of one complex work order: 
Refactor the entire authentication system to use JWT tokens
Submit multiple focused work orders: 
1. Add JWT utility functions to src/utils/jwt.ts
2. Update login endpoint to return JWT tokens
3. Add JWT validation middleware
4. Update protected routes to use new middleware

​
Security Considerations

​
API Key Management

Never commit API keys to source control.
  • Use environment variables
  • Rotate keys periodically
  • Use minimum necessary scopes
  • Different keys for different environments

​
Webhook Security

Always verify webhook signatures: 
function verifyWebhook(req: Request): boolean {
  const signature = req.headers['x-agentgate-signature'];
  const expected = computeSignature(req.body, WEBHOOK_SECRET);
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

​
Credential Handling

When work orders need credentials (private repos, APIs):
  • Configure credentials in AgentGate dashboard
  • Use environment variables in workspaces
  • Never include credentials in task prompts

​
Performance Tips

​
Use Webhooks

Webhooks are more efficient than polling:
ApproachAPI Calls per Run
Polling (5s interval, 5min run)60 calls
Webhooks1 callback

​
Concurrent Work Orders

AgentGate can run multiple work orders in parallel. For batch operations: 
// Submit all at once
const workOrders = await Promise.all(
  tasks.map(task => client.workOrders.create(task))
);

// Results come via webhooks

​
Webhook Processing

Process webhooks asynchronously to avoid timeouts: 
app.post('/webhooks/agentgate', (req, res) => {
  res.sendStatus(200); // Respond immediately
  processAsync(req.body); // Handle in background
});

​
Monitoring and Observability

​
Track Key Metrics

  • Success rate: Runs succeeded / total runs
  • Convergence speed: Average iterations to success
  • Cost per task: Credits used / tasks completed
  • Webhook latency: Time from completion to processing

​
Set Up Alerts

// Alert on unusual patterns
if (run.iterations >= maxIterations * 0.8) {
  alert('Run approaching iteration limit', run.id);
}

if (dailyUsage > usageBudget * 0.9) {
  alert('Approaching daily usage limit', dailyUsage);
}

​
Log for Debugging

Include correlation IDs for tracing: 
const requestId = generateId();

logger.info('Submitting work order', { requestId, taskPrompt });

const workOrder = await client.workOrders.create({
  ...config,
  metadata: { requestId }
});

logger.info('Work order created', { requestId, runId: workOrder.runId });

​
Common Pitfalls

Problem: “Make the code better”Solution: Be specific about what “better” means—faster, more readable, more secure, etc.
Problem: No tests to verify changesSolution: Include test requirements in prompts, or ensure existing tests cover the modified code.
Problem: High iteration counts indicate verification issuesSolution: Review failed runs to understand what’s failing and improve prompts or fix underlying issues.
Problem: Can’t attribute usage in B2B2C scenariosSolution: Always include tenant context for multi-tenant applications.

Integration Patterns

Common integration architectures

Error Handling

Handle errors gracefully