Gateway

Overview

The gateway sits between an agent and an external tool, such as an email service or an HTTP API. It decides whether the requested action is allowed, denied, or needs a human decision. Choose an authorization check to inspect policy without running the tool, a tool action to track approval, or gateway execution when you want the permitted action to run immediately.

Three routes, distinct effects

auth_checks returns allowed, denied, or requires approval as HTTP 200 and never executes. tool_actions writes audit/approval state but does not execute an already-allowed action. gateway/execute authorizes and immediately runs the connector only when policy says allowed.

Approval polling is observation

A tool action that needs approval returns 202, Location, Retry-After: 2, and a status URL. A permitted, signed-in operator's approval queues one execution attempt. The worker rechecks the connector, actor, freeze, and current authorization before running. Rejection or a failed recheck ends that attempt. Polling the status URL never starts execution or retries an interrupted attempt.

Policy fields have a shared envelope

Use the same connector, action, payload, amount, environment, risk_score, and contains_phi across check and execution. Authorization snapshots live in execution metadata and audit records, not as a top-level success field.

How it works

1. Preflight sensitive actions

   Run an auth check with real policy inputs. Branch on decision, not HTTP status, because denied and requires-approval decisions are valid 200 responses on this route.

2. Choose immediate or approval-aware flow

   Use gateway execute for an action expected to be allowed now. Use tool actions when a requires-approval result should create an operator request and expose a pollable state machine.

3. Retain execution evidence

   On direct execution, save the trace_id, connector, action, duration, events, and output. On approval flow, follow the returned status URL and stop polling according to state, next_action, and any retry-after value.

Examples

These examples are illustrative. Replace the sample values with your own. Keep credentials in environment variables or a secret manager, never in client-side code.

export AGENTOPS_BASE_URL="https://robotscenter.net"
export AGENT_TOKEN="machine_token_with_gateway_execute"

RESPONSE_HEADERS=$(mktemp)
RESPONSE_BODY=$(mktemp)
curl --silent --show-error \
  -D "$RESPONSE_HEADERS" -o "$RESPONSE_BODY" \
  -X POST -H 'content-type: application/json' \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  --data '{"connector_slug":"slack","action_name":"messages.post","payload":{"channel":"ops-alerts","text":"Investigate checkout alert"},"environment":"production","risk_score":0.4}' \
  "$AGENTOPS_BASE_URL/api/v1/tool_actions"

cat "$RESPONSE_HEADERS"
jq . "$RESPONSE_BODY"
rm -f "$RESPONSE_HEADERS" "$RESPONSE_BODY"

export AGENTOPS_BASE_URL="https://robotscenter.net"
export AGENT_TOKEN="machine_token_with_gateway_execute"

curl --fail-with-body --silent --show-error \
  -X POST -H 'content-type: application/json' \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  --data '{"connector_slug":"internal-api","action":"write","payload":{"job":"inventory-sync","requested_by":"agent-operations"},"environment":"production"}' \
  "$AGENTOPS_BASE_URL/api/v1/gateway/execute" | jq .

Troubleshooting

Auth check says allowed but execution fails

The check does not reserve policy state or test the external system. Recheck connector status, action support, current grant/policy state, outbound URL policy, and the executor events in the failed response.

A connector is 404

Machine lookup returns only active, non-archived connectors in the authenticated workspace. Missing and paused connectors are surfaced as not found on execution.

Polling does not start execution

That is intentional. Status GET is read-only, and automatic_retry is false. If state reports indeterminate execution or operator review, do not manufacture a retry that might duplicate the external side effect.

A lost POST response may hide a side effect

POST /tool_actions has no idempotency or deduplication: resending can create another approval request, and each duplicate can execute if approved. Reconcile the operator approval queue and audit trail with available request or business identifiers before resending. Non-SMTP /gateway/execute also ignores Idempotency-Key; HTTP executor retry: false prevents an internal transport retry but cannot prove a timed-out call did not reach the remote service. Only email-smtp send_email and send_bulk_email have the documented platform idempotency protection.

Endpoint reference

Ready to integrate? Open an endpoint for its required permissions, request fields, response format, and status codes. The examples above explain the workflow; these details define each individual request.

{
  "connector": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "slug": "email-smtp"
  },
  "decision": "allowed",
  "policy": null
}

{
  "status": "ok",
  "connector_id": "550e8400-e29b-41d4-a716-446655440000",
  "decision": "allowed"
}

{
  "status": "pending_approval",
  "connector_id": "550e8400-e29b-41d4-a716-446655440000",
  "decision": "requires_approval",
  "approval_request_id": "9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
  "status_url": "/api/v1/tool_actions/9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f"
}

{
  "output": {
    "delivered": true,
    "recipient": "recipient@example.com",
    "message_id": "<abc123@smtp.delivered>",
    "duration_ms": 245
  },
  "status": "success",
  "events": [
    {
      "timestamp": "2026-03-18T10:00:00Z",
      "type": "smtp_connecting",
      "details": {
        "port": 587,
        "host": "smtp.example.com"
      }
    },
    {
      "timestamp": "2026-03-18T10:00:00Z",
      "type": "smtp_connected",
      "details": {
        "port": 587,
        "host": "smtp.example.com"
      }
    },
    {
      "timestamp": "2026-03-18T10:00:01Z",
      "type": "smtp_authenticating",
      "details": {
        "user": "sender@example.com"
      }
    },
    {
      "timestamp": "2026-03-18T10:00:01Z",
      "type": "smtp_authenticated",
      "details": {
        "user": "sender@example.com"
      }
    },
    {
      "timestamp": "2026-03-18T10:00:02Z",
      "type": "email_sent",
      "details": {
        "from": "sender@example.com",
        "to": [
          "recipient@example.com"
        ],
        "subject": "Test Email",
        "message_id": "<abc123@smtp.delivered>"
      }
    },
    {
      "timestamp": "2026-03-18T10:00:02Z",
      "type": "smtp_disconnected",
      "details": {}
    }
  ],
  "action": "send_email",
  "message_id": "<abc123@smtp.delivered>",
  "trace_id": "a1b2c3d4e5f6",
  "duration_ms": 245,
  "connector_id": "550e8400-e29b-41d4-a716-446655440000",
  "connector_slug": "email-smtp"
}

{
  "message": "Failed to send email via SMTP",
  "status": "error",
  "events": [
    {
      "timestamp": "2026-03-18T10:00:00Z",
      "type": "smtp_connecting",
      "details": {
        "port": 587,
        "host": "smtp.example.com"
      }
    },
    {
      "timestamp": "2026-03-18T10:00:00Z",
      "type": "smtp_connected",
      "details": {
        "port": 587,
        "host": "smtp.example.com"
      }
    },
    {
      "timestamp": "2026-03-18T10:00:01Z",
      "type": "smtp_authentication_failed",
      "details": {
        "error": "Invalid credentials",
        "user": "sender@example.com"
      }
    },
    {
      "timestamp": "2026-03-18T10:00:01Z",
      "type": "smtp_disconnected",
      "details": {}
    }
  ],
  "details": {
    "action": "send_email",
    "provided_fields": [
      "action",
      "connector_id",
      "payload"
    ]
  },
  "error_code": "SMTP_ERROR",
  "trace_id": "a1b2c3d4e5f6"
}

{
  "id": "9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
  "state": "pending_approval",
  "expires_at": "2026-09-08T12:05:00Z",
  "retry_after_seconds": 2,
  "execution_status": "not_requested",
  "approval_status": "pending",
  "automatic_retry": false,
  "execution_completed_at": null,
  "execution_started_at": null,
  "execution_trace_id": null,
  "next_action": "poll",
  "reviewed_at": null
}