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

Good
Bad

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.

Add validation to the user service.

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:
Return early with a 400 error if email format is invalid
Return early with a 400 error if password is under 8 characters
Include specific error messages indicating which field failed
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

Smaller is Better

Large repositories take longer to clone and may hit size limits. Consider:

Using sparse checkout for monorepos
Excluding large binaries
Removing unnecessary history

Use Templates for Common Setups

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 Type	Suggested Limit
Simple changes	3-5 iterations
Medium complexity	5-10 iterations
Complex refactors	10-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:

Add JWT utility functions to src/utils/jwt.ts
Update login endpoint to return JWT tokens
Add JWT validation middleware
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:

Approach	API Calls per Run
Polling (5s interval, 5min run)	60 calls
Webhooks	1 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

Vague Task Prompts

Problem: “Make the code better”Solution: Be specific about what “better” means—faster, more readable, more secure, etc.

Missing Test Coverage

Problem: No tests to verify changesSolution: Include test requirements in prompts, or ensure existing tests cover the modified code.

Ignoring Verification Failures

Problem: High iteration counts indicate verification issuesSolution: Review failed runs to understand what’s failing and improve prompts or fix underlying issues.

Not Using Tenant Context

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

​Best Practices

​Task Prompt Engineering

​Be Specific

​Provide Context

​Define Acceptance Criteria

​Specify Constraints

​Workspace Optimization

​Keep Repositories Focused

​Ensure Reproducibility

​Configure for Automation

​Cost Optimization

​Right-Size Iteration Limits

​Use Appropriate Verification

​Break Down Complex Tasks

​Security Considerations

​API Key Management

​Webhook Security

​Credential Handling

​Performance Tips

​Use Webhooks

​Concurrent Work Orders

​Webhook Processing

​Monitoring and Observability

​Track Key Metrics

​Set Up Alerts

​Log for Debugging

​Common Pitfalls

​Related

Integration Patterns

Error Handling

Best Practices

Task Prompt Engineering

Be Specific

Provide Context

Define Acceptance Criteria

Specify Constraints

Workspace Optimization

Keep Repositories Focused

Ensure Reproducibility

Configure for Automation

Cost Optimization

Right-Size Iteration Limits

Use Appropriate Verification

Break Down Complex Tasks

Security Considerations

API Key Management

Webhook Security

Credential Handling

Performance Tips

Use Webhooks

Concurrent Work Orders

Webhook Processing

Monitoring and Observability

Track Key Metrics

Set Up Alerts

Log for Debugging

Common Pitfalls

Related