Best Practices

Context Requests

• Always call before responding: Get context before every user interaction
• Provide descriptive tasks: Better task descriptions = better recommendations
• Include task type when possible: Helps AMP learn context-specific patterns
• Cache sparingly: Profiles update frequently, stale data hurts performance

// Good: Descriptive task
const context = await amp.getContext({
  userId: user.id,
  task: "fix authentication bug in login form",
  taskType: "debugging"
});

// Bad: Vague task
const context = await amp.getContext({
  userId: user.id,
  task: "help"
});

Outcome Reporting

• Always report outcomes: Even negative ones - especially negative ones!
• Track real behaviour: Don't make optimistic assumptions
• Report in background: Don't block user interactions
• Include optional fields: timeToStart, flowState, satisfaction

Error Handling

• Always have fallbacks: Your agent should work if AMP is down
• Implement retry logic: Use exponential backoff for rate limits
• Log errors: But don't expose them to users
• Monitor API health: Track success rates and latency

Performance

• Parallel requests when possible: Don't wait unnecessarily
• Use async/await properly: Don't block the event loop
• Monitor response times: AMP should add < 50ms latency
• Consider caching for high-traffic: But keep TTL short (< 5 min)

Security

• Never expose API keys: Use environment variables
• Use different keys per environment: Dev, staging, production
• Rotate keys regularly: Every 90 days recommended
• Hash sensitive user IDs: Don't send PII to AMP

Testing

• Use test mode for development: Free unlimited requests
• Test all framing types: Ensure your agent handles each
• Mock AMP in unit tests: Don't hit the API in CI
• Monitor profile evolution: Ensure learning is happening

See Also

• Testing & Debugging
• Production Checklist