Skip to content
AX Framework

Implementation

API Integration

Making existing REST and GraphQL APIs agent-ready.

Many products already have an HTTP or GraphQL API. It was usually designed for developers who read the documentation once and write code against it. Agents are different: they read the description at runtime, choose operations on the fly, and need the API to explain itself. This page covers how to make an existing API agent-ready without rebuilding it.

Describe it with OpenAPI

If your HTTP API has no machine-readable description, start there. OpenAPI is the established format and many agent frameworks can turn an OpenAPI document into callable tools.

OpenAPI Specification

Write descriptions for agents, not just for reference docs:

yaml
paths:
  /orders/{orderId}/returns:
    post:
      operationId: start_return
      summary: Start a return for items in a delivered order.
      description: >
        Creates a return and a prepaid shipping label. Only delivered orders within
        30 days of delivery are eligible. Safe to retry with the same Idempotency-Key.
      x-ax-risk: medium
      x-ax-scopes: [returns:create]
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema: { type: string }

The x-ax-* extensions are an AX proposal. OpenAPI allows vendor extensions prefixed with x-, so they do not break existing tooling.

Five upgrades with the biggest payoff

1. Operation IDs as verbs

Agents pick operations by name. start_return is self-explanatory; post_orders_orderId_returns is not.

2. Idempotency on mutations

Accept an Idempotency-Key header on every operation that creates, charges, or sends. See Retry Strategies.

3. Problem Details for errors

Return errors in RFC 9457 format with AX extensions (code, retryable, suggestions). See Error Handling.

4. Available actions on resources

Include an actions array on resources so agents know what is possible in the current state. See Action Discovery.

5. Scoped tokens

If your API accepts a single all-powerful API key, add OAuth scopes so people can delegate narrowly. See Permissions and Trust.

GraphQL

GraphQL's introspection makes the schema discoverable, but discoverable is not the same as understandable. Apply the same principles:

  • Write descriptions on every type, field, and mutation.
  • Use enums instead of strings for fixed values.
  • Return a union of result types from mutations so outcomes are explicit:
graphql
"""Start a return for items in a delivered order. Requires returns:create."""
startReturn(input: StartReturnInput!, idempotencyKey: String!): StartReturnResult!

union StartReturnResult = ReturnCreated | ApprovalRequired | ReturnWindowClosed | InvalidOrderState

Pagination and limits

Agents may try to fetch everything. Use cursor pagination with documented maximum page sizes, and return totals so agents can decide whether to continue:

json
{ "data": [], "page": { "next": "c_9f2", "size": 50, "total": 812 } }

Last updated 2026-10-06. AX Framework documentation describes proposals unless a section is marked as an established standard.