Action Builder

When to use this API

Use the Action Builder when a decision should lead to something being done, and other software, an AI agent or a person needs to ask for it.

An action is built in the console from a decision policy of the Logic Controller. You choose the interfaces it ships as (a chat, an API, an MCP server, an A2A agent, a schedule or a connector) and its oversight: whether a person approves before it acts (the default) or reviews after. Every request and every decision is written to the audit log.

Authentication

Every interface takes the action's API key. Create one in the console under the action's API & integration. A key opens this one action only, is shown once (only a hash of it is kept) and can be set to expire after 30, 90 or 365 days; rotate it with a grace period, or revoke it at once. Keys start with ok_live_.

x-ok-api-key: ok_live_xxxxxxxxxxxxxxxxxxxxxxxx
Authorization: Bearer ok_live_xxxxxxxxxxxxxxxxxxxxxxxx

Parameters

Path

The agent card

GET /a2a/{actionId}/.well-known/agent-card.json is public and describes the action to other agents: its endpoint, the security schemes (x-ok-api-key or bearer) and its skills. Send A2A-Version: 1.0 for the 1.0 form; without it the card is served in the 0.3 form. The card is offered once the action is deployed with A2A among its interfaces.

Skills

Name the skill in message.metadata.skill (or skill in a data part) and put its input in a data part. A plain-text message with no skill is taken as a question.

Request

Ask the action to act on a record (A2A 1.0, SendMessage):

curl -X POST https://okp.openknowra.ai/a2a/$ACTION_ID \
  -H "x-ok-api-key: $OPENKNOWRA_ACTION_KEY" \
  -H "Content-Type: application/json" \
  -H "A2A-Version: 1.0" \
  -d '{"jsonrpc":"2.0","id":1,"method":"SendMessage","params":{"message":{"messageId":"m-1","role":"ROLE_USER",
       "metadata":{"skill":"request_action"},
       "parts":[{"data":{"key":"WO-2291","entity":"WorkOrder","reason":"Crew available on site today"}}]}}}'

import os, json, urllib.request

body = {"jsonrpc": "2.0", "id": 1, "method": "SendMessage", "params": {"message": {
    "messageId": "m-1", "role": "ROLE_USER", "metadata": {"skill": "request_action"},
    "parts": [{"data": {"key": "WO-2291", "entity": "WorkOrder", "reason": "Crew available on site today"}}]}}}
req = urllib.request.Request(
    "https://okp.openknowra.ai/a2a/" + os.environ["ACTION_ID"],
    data=json.dumps(body).encode(),
    headers={"x-ok-api-key": os.environ["OPENKNOWRA_ACTION_KEY"], "Content-Type": "application/json",
             "A2A-Version": "1.0"},
    method="POST")
print(json.load(urllib.request.urlopen(req, timeout=30)))

const res = await fetch(`https://okp.openknowra.ai/a2a/${process.env.ACTION_ID}`, {
  method: "POST",
  headers: { "x-ok-api-key": process.env.OPENKNOWRA_ACTION_KEY!, "Content-Type": "application/json", "A2A-Version": "1.0" },
  body: JSON.stringify({
    jsonrpc: "2.0", id: 1, method: "SendMessage",
    params: { message: { messageId: "m-1", role: "ROLE_USER", metadata: { skill: "request_action" },
      parts: [{ data: { key: "WO-2291", entity: "WorkOrder", reason: "Crew available on site today" } }] } },
  }),
});
console.log(await res.json());

Response

200 OK - a task. With approves before it acts, a request_action task stays working until a person decides in the console:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "task": {
      "id": "8f1c2a90-4b7e-4d2a-9a51-1b2c3d4e5f60",
      "contextId": "c-77b1",
      "status": {
        "state": "TASK_STATE_WORKING",
        "message": { "role": "ROLE_AGENT", "parts": [{ "text": "Awaiting approval by the action's approvers: Field dispatch acts on WO-2291 once a person approves. Read the outcome with GetTask." }] }
      }
    }
  }
}

Poll the task with GetTask until it settles:

curl -X POST https://okp.openknowra.ai/a2a/$ACTION_ID \
  -H "x-ok-api-key: $OPENKNOWRA_ACTION_KEY" -H "Content-Type: application/json" -H "A2A-Version: 1.0" \
  -d '{"jsonrpc":"2.0","id":2,"method":"GetTask","params":{"id":"8f1c2a90-4b7e-4d2a-9a51-1b2c3d4e5f60"}}'

MCP server

The action is also an MCP server (Streamable HTTP, JSON-RPC 2.0) at https://okp.openknowra.ai/api/okp/mcp/{actionId}, with the tools describe_decisions, decide, get_decision and list_decisions. They read recommendations; asking the action to act is A2A's request_action.

{
  "mcpServers": {
    "field-dispatch": {
      "type": "http",
      "url": "https://okp.openknowra.ai/api/okp/mcp/<actionId>",
      "headers": { "Authorization": "Bearer ok_live_xxxxxxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

REST

The action answers the same REST API as its decision policy, relative to https://okp.openknowra.ai/api/okp/d/{actionId}: GET / (describe), POST /decide, GET /decisions, GET /decisions/{entity}/{key}, POST /events and GET /openapi.json. The request and response shapes are on the Logic Controller page.

curl https://okp.openknowra.ai/api/okp/d/$ACTION_ID/decisions/WorkOrder/WO-2291 \
  -H "x-ok-api-key: $OPENKNOWRA_ACTION_KEY"

Webhooks

Under API & integration, add a webhook to be told when a record gains or loses an outcome (rule_result.gained, rule_result.lost) or a new version is deployed (version.published). Deliveries are signed with your secret in x-ok-signature (sha256= HMAC of timestamp + "." + body, with x-ok-timestamp in milliseconds) and sent once with an 8-second timeout. The headers, payloads and a verification example are on the Logic Controller page.

Website chat

Paste the action's chat into any page; people ask it in plain words and get its recommendations.

<script src="https://okp.openknowra.ai/okplatform/widget.js"
        data-agent="<actionId>" data-key="ok_live_xxxxxxxxxxxxxxxxxxxxxxxx"
        data-title="Field dispatch" data-position="right"></script>

Optional attributes: data-title, data-color, data-position (right or left), data-open="true", data-inline (a CSS selector to render into) and data-theme (light or dark).

Pricing

Requests over A2A, MCP and REST, and webhook deliveries, carry no per-call charge. Questions people ask in the website chat are billed as Natural Language Queries, and the context graph the action decides on is billed under the Context Compiler. The APIs, AI agents and workers an action can call are priced on their own cards: Action Builder pricing.

Errors

A2A and MCP answer with JSON-RPC errors; REST and the chat with { "error", "message" }.