Agent Integration Guide

{
  "targetUrl": "https://api.stripe.com/v1/charges",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": "{\"amount\": 500, \"currency\": \"usd\", \"customer\": \"cus_123\"}",
  "intent": "Charge customer $5.00 for monthly subscription renewal",
  "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000"
}

import time
import requests

GATEWAY_URL = "http://localhost:3000"
AGENT_KEY = "agt_a1b2c3d4..."
ACTION_ID = "550e8400-e29b-41d4-a716-446655440000"

POLL_INTERVAL = 8  # seconds
MAX_POLLS = 75

for attempt in range(MAX_POLLS):
    response = requests.get(
        f"{GATEWAY_URL}/status/{ACTION_ID}",
        headers={"Agent-Key": AGENT_KEY}
    )

    if response.status_code != 200:
        print(f"Status poll error {response.status_code}")
        time.sleep(POLL_INTERVAL)
        continue

    data = response.json()
    status = data["status"]
    print(f"Attempt {attempt + 1}: {status}")

    if status == "PENDING":
        time.sleep(POLL_INTERVAL)
        continue

    elif status == "APPROVED":
        print("Approved - executing...")
        # Proceed to Step 3
        break

    elif status == "DENIED":
        print(f"Denied at {data.get('resolved_at')}")
        # Handle gracefully
        break

    elif status == "EXPIRED":
        print("Approval expired - resubmit via POST /proxy")
        break

    elif status == "EXECUTED":
        # Already executed (concurrent poll)
        result = data["result"]
        print(f"Already executed: HTTP {result['status']}")
        print(result["body"])
        break

else:
    print("Max polls reached - giving up")

response = requests.post(
    f"{GATEWAY_URL}/proxy/execute/{ACTION_ID}",
    headers={"Agent-Key": AGENT_KEY}
)

if response.status_code in (200, 201, 202, 204):
    print(f"Executed successfully: HTTP {response.status_code}")
    print(response.json())
elif response.status_code == 410:
    print("Approval expired before execution")
    # Resubmit via POST /proxy
elif response.status_code == 409:
    print(f"Cannot execute: {response.json()['error']}")
    # Check status again
else:
    print(f"Execute failed: {response.status_code}")
    print(response.json())

#!/usr/bin/env python3
import time, json, requests, uuid

GATEWAY_URL = "http://localhost:3000"
AGENT_KEY = "agt_a1b2c3d4..."

def proxy_request(target_url, method, body, intent):
    """Submit request via POST /proxy"""
    response = requests.post(
        f"{GATEWAY_URL}/proxy",
        headers={
            "Agent-Key": AGENT_KEY,
            "Content-Type": "application/json",
            "Idempotency-Key": str(uuid.uuid4())
        },
        json={
            "targetUrl": target_url,
            "method": method,
            "headers": {"Content-Type": "application/json"},
            "body": json.dumps(body) if body else None,
            "intent": intent
        }
    )

    if response.status_code in (200, 201, 202, 204):
        return {"status": "forwarded", "data": response.json()}
    elif response.status_code == 428:
        data = response.json()
        print(f"[428] Risk blocked: {data['risk_explanation']}")
        return {"status": "blocked", "action_id": data["action_id"]}
    else:
        raise Exception(f"Proxy failed: {response.status_code} {response.text}")

def poll_approval(action_id, max_polls=75, interval=8):
    """Poll GET /status/:actionId until terminal state"""
    for attempt in range(max_polls):
        response = requests.get(
            f"{GATEWAY_URL}/status/{action_id}",
            headers={"Agent-Key": AGENT_KEY}
        )
        data = response.json()
        status = data["status"]
        print(f"  Poll {attempt+1}: {status}")

        if status == "PENDING":
            time.sleep(interval)
        elif status == "APPROVED":
            return {"status": "approved"}
        elif status == "DENIED":
            return {"status": "denied"}
        elif status == "EXPIRED":
            return {"status": "expired"}
        elif status == "EXECUTED":
            return {"status": "executed", "result": data["result"]}
        else:
            raise Exception(f"Unknown status: {status}")

    raise Exception("Max polls reached")

def execute_approved(action_id):
    """Execute via POST /proxy/execute/:actionId"""
    response = requests.post(
        f"{GATEWAY_URL}/proxy/execute/{action_id}",
        headers={"Agent-Key": AGENT_KEY}
    )

    if response.status_code in (200, 201, 202, 204):
        return response.json()
    elif response.status_code == 410:
        raise Exception("Approval expired before execution")
    else:
        raise Exception(f"Execute failed: {response.status_code} {response.text}")

# Example usage
if __name__ == "__main__":
    # Submit a high-risk DELETE request
    result = proxy_request(
        target_url="https://api.example.com/v1/users/123",
        method="DELETE",
        body=None,
        intent="Delete inactive test user account"
    )

    if result["status"] == "forwarded":
        print("Request forwarded directly")
        print(result["data"])

    elif result["status"] == "blocked":
        action_id = result["action_id"]
        print(f"Polling for approval: {action_id}")

        poll_result = poll_approval(action_id)

        if poll_result["status"] == "approved":
            print("Executing approved request...")
            exec_result = execute_approved(action_id)
            print("Execution result:")
            print(exec_result)

        elif poll_result["status"] == "denied":
            print("Request denied by human")

        elif poll_result["status"] == "expired":
            print("Approval expired - resubmit if still needed")

        elif poll_result["status"] == "executed":
            print("Already executed:")
            print(poll_result["result"])