Approval Flows

How It Works

When your agent needs approval, it calls the request_approval tool. The flow is:

1. Agent calls request_approval with a message
2. You receive an SMS/email with the request
3. You reply with your decision
4. Agent receives the response and continues

Request Types

Yes/No Approvals

Simple binary decisions. The agent waits for YES or NO.

await mcp.callTool("request_approval", {
  message: "Deploy v2.1.0 to production?",
  type: "yes_no"
});
// Returns: { approved: true/false, response: "YES" }

Multiple Choice

Present options for the human to choose from.

await mcp.callTool("request_approval", {
  message: "How should I handle this error?",
  type: "multiple_choice",
  options: ["Retry", "Skip", "Abort"]
});
// Returns: { choice: "Retry", response: "1" }

Free-form Input

When you need detailed human input.

await mcp.callTool("request_approval", {
  message: "What commit message should I use?",
  type: "freeform"
});
// Returns: { response: "Fix auth bug in login flow" }

Timeout Handling

By default, approval requests timeout after 1 hour. You can customize this:

await mcp.callTool("request_approval", {
  message: "Deploy to production?",
  timeout_minutes: 30  // Timeout after 30 minutes
});

If the request times out, the agent receives a timeout response and should handle it gracefully.

Web Response Page

For complex approvals, RelayRail includes a link to a web page where you can:

• View the full context of the request
• See any attached files or logs
• Respond with a detailed message

This is especially useful when you receive requests on your phone but need to respond from your computer.

Best Practices

• 1.Be specific - Include relevant details in your message
• 2.Use appropriate types - Yes/No for simple decisions, multiple choice when options are clear
• 3.Set reasonable timeouts - Don't make urgent requests wait too long
• 4.Handle timeouts gracefully - Your agent should have a fallback plan