AgenticOS Building Blocks: HTTP Transitions – External API Integration

Posted on

HTTP Transitions – External API Integration in AgetnticOS

HTTP transitions connect your agentic processes to the outside world. They make REST API calls, process responses, handle authentication, implement retry logic, and route results based on HTTP status codes or response content.

HTTP Transition: External API Call request tokens HTTP POST /api/orders with auth + retry External API success 2xx error 4xx/5xx emit.from: @response.json parsed body

HTTP transitions call external APIs and emit parsed response data to success or error places.

Basic HTTP Inscription Structure

{
  "id": "t-call-api",
  "kind": "http",
  "mode": "SINGLE",

  "presets": {
    "input": {
      "placeId": "api-requests",
      "host": "myModel@localhost:8080",
      "arcql": "FROM $ LIMIT 1",
      "take": "FIRST",
      "consume": true
    }
  },

  "postsets": {
    "success": { "placeId": "api-success", "host": "myModel@localhost:8080" },
    "error": { "placeId": "api-error", "host": "myModel@localhost:8080" }
  },

  "action": {
    "type": "http",
    "method": "POST",
    "url": "https://api.example.com/orders",
    "headers": {
      "Content-Type": "application/json"
    },
    "body": {
      "orderId": "${input.data.orderId}",
      "amount": "${input.data.amount}"
    }
  },

  "emit": [
    { "to": "success", "from": "@response.json", "when": "success" },
    { "to": "error", "from": "@response.json", "when": "error" }
  ]
}

Key components:

  • kind: "http" – identifies this as an HTTP transition
  • action.method – GET, POST, PUT, DELETE, PATCH
  • action.url – target endpoint (supports ${...} interpolation)
  • action.body – request body with template interpolation
  • emit.from: "@response.json" – emits parsed JSON response body

Response Data Access

HTTP transitions provide two ways to access response data:

HTTP Response Access Patterns @response.json The parsed JSON response body: { “orderId”: “123”, “status”: “ok” } Use for: routing by response content @response.meta HTTP metadata (status, headers): { “status”: 200, “headers”: {…} } Use for: routing by status code 
<pre class="wp-block-syntaxhighlighter-code">// Route by response content
"emit": [
  { "to": "created", "from": "@response.json", "when": "status == 'created'" },
  { "to": "updated", "from": "@response.json", "when": "status == 'updated'" }
]

// Route by HTTP status code
"emit": [
  { "to": "success", "from": "@response.meta", "when": "status >= 200 AND status < 300" },
  { "to": "error", "from": "@response.meta", "when": "status >= 400" }
]</pre>

Authentication Methods

HTTP transitions support multiple authentication schemes:

Basic Authentication

"action": {
  "type": "http",
  "method": "GET",
  "url": "https://api.example.com/protected",
  "auth": {
    "type": "basic",
    "username": "myuser",
    "password": "mypassword"
  }
}

Bearer Token

"action": {
  "type": "http",
  "method": "GET",
  "url": "https://api.example.com/data",
  "auth": {
    "type": "bearer",
    "token": "eyJhbGciOiJIUzI1NiIs..."
  }
}

API Key

"action": {
  "type": "http",
  "method": "GET",
  "url": "https://api.example.com/data",
  "auth": {
    "type": "api_key",
    "key": "X-API-Key",
    "value": "my-secret-key",
    "in": "header"  // or "query"
  }
}

Retry Configuration

HTTP transitions support automatic retry with exponential backoff:

"action": {
  "type": "http",
  "method": "POST",
  "url": "https://api.example.com/orders",
  "retry": {
    "maxAttempts": 3,
    "initialDelayMs": 1000,
    "multiplier": 2.0,
    "retryOn": ["5xx", "429", "io_error"]
  }
}

Retry conditions:

  • 5xx – server errors (500, 502, 503, etc.)
  • 429 – rate limiting
  • io_error – network failures, timeouts

URL and Body Interpolation

Both URL and body support template interpolation from token data:

"action": {
  "type": "http",
  "method": "GET",
  "url": "https://api.example.com/orders/${input.data.orderId}",
  "headers": {
    "X-Request-Id": "${input._meta.id}"
  }
}

// POST with interpolated body
"action": {
  "type": "http",
  "method": "POST",
  "url": "https://api.example.com/orders",
  "body": {
    "orderId": "${input.data.orderId}",
    "customer": "${input.data.customerName}",
    "items": "${input.data.lineItems}",
    "requestedBy": "${input._meta.name}"
  }
}

Complete Example: Order Processing API

Order Processing: HTTP → Route by Response pending orders t-process-order POST /api/orders bearer auth + retry confirmed orders pending review failed orders status==”confirmed” status==”pending_review” when: “error” Response Example { “orderId”: “123”, “status”: “confirmed”, “total”: 299.99 } @response.json.status 
{
  "id": "t-process-order",
  "kind": "http",
  "mode": "SINGLE",

  "presets": {
    "input": {
      "placeId": "pending-orders",
      "host": "orders-model@localhost:8080",
      "arcql": "FROM $ WHERE $.data.status==\"pending\" LIMIT 1",
      "take": "FIRST",
      "consume": true
    }
  },

  "postsets": {
    "confirmed": { "placeId": "confirmed-orders", "host": "orders-model@localhost:8080" },
    "review": { "placeId": "pending-review", "host": "orders-model@localhost:8080" },
    "failed": { "placeId": "failed-orders", "host": "orders-model@localhost:8080" }
  },

  "action": {
    "type": "http",
    "method": "POST",
    "url": "https://api.orders.com/v1/process",
    "headers": { "Content-Type": "application/json" },
    "body": {
      "orderId": "${input.data.orderId}",
      "amount": "${input.data.amount}",
      "customer": "${input.data.customerName}"
    },
    "auth": {
      "type": "bearer",
      "token": "${env.ORDERS_API_TOKEN}"
    },
    "retry": {
      "maxAttempts": 3,
      "initialDelayMs": 1000,
      "retryOn": ["5xx", "429"]
    },
    "timeoutMs": 30000
  },

  "emit": [
    { "to": "confirmed", "from": "@response.json", "when": "status == 'confirmed'" },
    { "to": "review", "from": "@response.json", "when": "status == 'pending_review'" },
    { "to": "failed", "from": "@response.json", "when": "error" }
  ]
}

Summary

  • kind: “http” – identifies the transition type
  • emit.from: “@response.json” – parsed JSON response body
  • emit.from: “@response.meta” – HTTP status and headers
  • Authentication – basic, bearer, api_key
  • Retry – automatic with exponential backoff
  • Template interpolation – URL, headers, and body support ${...}

HTTP transitions bridge your Petri nets to external systems – use them for API integrations, webhooks, and service-to-service communication.

Leave a Reply

Your email address will not be published. Required fields are marked *