agentic.json
Agentic Action Profile · 0.1 draft

Give agent actions
a verifiable outcome.

agentic.json describes how an AI agent checks whether an action completed and recovers an interrupted request. One JSON profile, connected to your existing API.

Read the specification Build a profile

Open source · No registry required · Experimental proposal

your-service.example / agentic.jsonDownload ↓
{
  "$schema": "https://ruagentic.org/schemas/agentic-0.1.schema.json",
  "agentic": "0.1.0-draft",
  "origin": "https://support.example",
  "actions": [
    {
      "id": "create-ticket",
      "description": "Create a support ticket and verify the original result.",
      "openapi": "/openapi.json",
      "submit": "createTicket",
      "status": "getRequestStatus",
      "verify": "getTicket",
      "request": {
        "header": "Idempotency-Key",
        "scope": "principal-action",
        "retentionSeconds": 86400
      },
      "bindings": {
        "statusRequestId": "requestId",
        "verifyResourceId": "ticketId"
      },
      "evidence": {
        "resourceIdPointer": "/id",
        "requestIdPointer": "/request_id",
        "statePointer": "/status",
        "successValues": [
          "open",
          "closed"
        ],
        "inputBindings": [
          {
            "inputPointer": "/subject",
            "resourcePointer": "/subject"
          }
        ]
      },
      "recovery": {
        "maxChecks": 3,
        "checkDelayMs": 100,
        "timeoutMs": 3000,
        "retry": "never-automatically"
      }
    }
  ]
}
Complete ticket example · Service behavior must match the fileExplore the example →

Start with one action.

Choose a service operation that already supports idempotency and request-status lookup.

1

Describe the contract

Connect the submit, status, and resource-read operations. Specify the evidence that establishes success.

2

Publish the profile

Serve /agentic.json on your service or give its URL to a supporting client. Validate it with your OpenAPI document.

3

Test the interruption

Lose a response after a committed action. Reconcile the original request and verify the resulting resource.

Full quick start →Run the recovery lab →

A durable request identity

Bind each attempt to its original input before sending. Keep that identity through a restart.

Recovery after interruption

Use the service’s status operation to find out what happened when a submission response is lost.

Evidence before success

Check the resulting resource, its request identity, and the input values that matter.

Your existing OpenAPI

Reference three operations in an OpenAPI 3.1 document. Keep your API as the source of truth.

A portable receipt

Return a structured observation of the outcome that the host can retain and inspect.

An honest unknown

When evidence is unavailable or inconsistent, preserve uncertainty for the host to resolve.

Generate. Validate. Implement.

The repository includes local tools, schemas, and Node and Python reference clients.

git clone https://github.com/sam1siam/agentic.git
cd agentic
npm ci
npm run init -- --origin https://your-service.example --out agentic.json
npm run validate -- agentic.json examples/tickets/openapi.json

Requires Node 24. The generator starts from the ticket contract; adapt it to your service before publishing. A package has not been published to npm.

Browse the documentation →View on GitHub ↗

Independent pilot cohort

Help put the proposal to the test.

Bring a client or a service. Compare it with your current workflow and publish what works, what breaks, and what should change.

Join a pilot