Action ≠ API: Designing Business Execution Contracts for Enterprise Agents

The previous article discussed where business rules belong — ontology, validation mechanisms, rule engines, workflows, or business code. Once semantic and rule boundaries are clear, ontology intelligence faces a harder engineering problem: how decisions safely become actions.

For example, the decision layer concludes:

Recommend adjusting the credit limit for customer CUS-001 to 500,000.

The business system already has an adjust_credit_limit API, but that does not mean the Agent can call it directly. The API may only specify path, parameters, and return values, without stating whether the customer currently allows a limit change, which rules and evidence the decision relies on, who has approved, whether repeated calls cause duplicate changes or notifications, and whether a successful response truly means the business state has changed.

API describes "how to invoke"; an action contract must describe "under what business conditions, by whom, after what confirmation, how to safely change object state, and how to prove the action is complete."

Action in Ontology Is First a Business Capability Definition

Here, Action does not mean RDF or OWL provides a directly executable action type. Rather, it is the enterprise's modeling of operable business capabilities in its business ontology or semantic platform.

An Action Type should define:

Which class of business object it targets;

Its business meaning and applicable scenarios;

Which object states allow execution;

What facts, evidence, rules, and permissions are required before execution;

What object or attribute changes, state transitions, business events, and audit results should be produced on success.

Therefore, "adjust credit limit" is not just an interface name. It expresses: for a specific customer object, under specific credit state, evidence, and authorization conditions, change the limit from the current value to a target value, and produce a traceable limit-change event.

Action Type is a reusable, versionable semantic anchor — the enterprise's unified definition of this business capability. A complete action contract further binds input structure, decision and approval policies, execution service, and receipt semantics. A specific limit-adjustment request for CUS-001 is a concrete action request; only after controlled execution does it produce an execution record and receipt.

An Action Goes Through Four Distinct Forms

From governance to runtime, an Action produces at least four distinct engineering artifacts along the timeline:

Action Definition — created at capability design and release; contains object, semantics, preconditions, policies, execution mapping, expected effects, and version; owned by semantic platform and business owner.

Action Request — created after business intent or decision forms; contains target object, parameters, decision, evidence, initiator, and approval requirements; owned by business application, decision service, or Agent Runtime.

Execution Record — created when request enters controlled execution chain; contains execution path, idempotency key, approval or transaction number, current state, and exception info; owned by workflow, action gateway, and business system.

Execution Receipt — created when state updates, completes, or terminates; contains current or final state, object changes, business events, failure reasons, and audit references; owned by business system and action gateway.

These four artifacts are generated sequentially over time; they are not a single API payload and should not be freely generated by the Agent in one shot. The Agent may submit a candidate action request, but the request must first pass contract, identity, real-time state, and rule validation; high-risk requests must also complete necessary human confirmation before entering formal business execution.

Action Contract Must Lock Down Five Categories of Boundaries

First, Semantic Boundary. What object the action targets, what each parameter means, what objects, attributes, relationships, or processes are created or modified on success, and if state transitions are involved, which states are allowed as source and target. These definitions must reference unified object, attribute, relationship, state, and event semantics, not just interface field names.

Second, Decision and Evidence Boundary. Which decision record the invocation references, which rule version is used, which business facts and evidence are relied upon, and whether those evidences remain valid at execution time. A formed decision does not mean execution can skip re-validation of real-time state and critical evidence.

Third, Permission and Human Confirmation Boundary. Who can initiate, under what identity to execute, which risk level requires human confirmation, and whether the approver's permissions cover the current object and action. Human approval should apply to a fully parameterized, evidenced, and versioned action request. If the target limit or key evidence changes, the original approval must not remain automatically valid.

Fourth, Transaction and Failure Semantics Boundary. How to generate a business idempotency key, how to prevent concurrent update overwrites, which failures are retryable and which must pause, reconcile, or escalate to manual intervention. If the same idempotency key is used with different request parameters, it should return a conflict, not be treated as a retry.

If an action spans multiple systems and partial success occurs, a compensating transaction must be defined, and operations like reversal, cancellation, or refund must be modeled as controlled compensating actions. When using Saga or other distributed transaction patterns, compensation is not a database-level rollback but a new business action, thus requiring the same permission, idempotency, and audit constraints.

These guarantees must reside close to the real transaction and state authority, implemented by business services, databases, workflows, and runtime mechanisms — not merely written in ontology or prompts.

Fifth, Result and Audit Boundary. HTTP success may only mean the request was received, not that business is complete. The action receipt must distinguish at least: accepted, pending approval, executing, succeeded, failed, and unknown. It must also state what exactly changed on the object, what events were produced, and return transaction numbers, evidence, and log references usable for reconciliation and audit.

Action Contract Is a Verifiable Governance Definition, Not a Single Call Payload

The simplified structure below describes the "adjust credit limit" action definition, not the payload passed to an API at execution time:

{
  "action_type": "AdjustCreditLimit",
  "contract_version": "1.4",
  "target_object_type": "Customer",
  "allowed_from_states": ["credit_normal", "credit_warning"],
  "input_schema_ref": "schema:[email protected]",
  "precondition_refs": [
    "fact:[email protected]",
    "policy:[email protected]"
  ],
  "risk_level": "high",
  "approval_policy_ref": "policy:[email protected]",
  "idempotency_key_fields": ["target_object_id", "decision_id"],
  "failure_policy_ref": "policy:[email protected]",
  "executor_ref": "service:[email protected]",
  "success_effect_ref": "effect:[email protected]",
  "receipt_schema_ref": "schema:[email protected]"
}

Its value is not to centralize all execution logic in one JSON, but to let the action definition reference already-published semantics, rules, policies, execution services, and receipt structures. A runtime request only needs to bind the contract version and provide instance information such as target object, parameters, decision, evidence, and authorization.

Internal contract references should point to immutable version baselines. Requests already in approval or execution must not silently switch due to policy or service mapping upgrades. The specific reference format can be designed by the enterprise platform; the fields above are not a universal industry standard.

One Action Often Maps to Multiple APIs

API is a technical interface; Action is a stable business capability. The two are not necessarily one-to-one.

A single "adjust credit limit" may require:

Query customer current state and data version;

Validate decision, evidence, authorization, and contract version;

Initiate human approval workflow based on risk level;

After approval, call CRM's limit adjustment service;

Query asynchronous task or transaction final state;

Generate business events, execution receipt, and audit records.

Thus, one Action may map to one API, or to "workflow + multiple business services + async events". Conversely, a generic update_customer API that can modify many fields should not be directly wrapped as a high-privilege action for Agent use.

The value of the action contract is precisely to use stable business semantics to isolate backend technical implementation changes.

MCP Tool Is a Publishing Entry, Not Execution Authority

MCP Server can publish Actions as discoverable and callable tools for Agents, providing tool name, semantic description, input structure, and output structure. But it mainly solves capability discovery and invocation; it does not automatically gain business decision authority, authorization authority, or transaction control capability.

Further distinction: not every MCP tool is an Action. Query, retrieval, and explanation tools can be read-only; they still need permission and query contracts but do not require the same strength of transaction, idempotency, and compensation mechanisms. Only when a tool creates tasks, modifies state, sends instructions, or produces transactions must it enter the full action contract and controlled execution chain.

A more reasonable execution chain is:

Agent / Runtime → MCP Tool → Action Gateway or Workflow → Controlled Business Service → Execution Receipt

The action gateway here is a logical responsibility: validate action contract, identity, real-time state, decision basis, and approval result, then route the request to the real business service. It does not have to be a new standalone product; existing API gateway, policy service, workflow, and business service can jointly fulfill it.

Regardless of composition, the source business system must re-validate key invariants before committing the transaction and remain responsible for the final state change. The semantic platform can define allowed state transitions but should not replace the source system's transaction authority.

Four Common Misconceptions

First, treating OpenAPI or JSON Schema as the action contract. They can constrain parameter structure but cannot necessarily express object state, decision basis, authorization conditions, human confirmation, idempotency, and compensation semantics.

Second, treating HTTP success as business success. For asynchronous actions, the request may still await approval, execution, or reconciliation after being received. The Agent must judge completion based on business receipt and state query; when state is unknown, it must not self-declare success or failure but pause and enter reconciliation.

Third, hiding action boundaries in prompts. Prompts can help the Agent understand when to propose an action, but cannot serve as the sole execution mechanism for permissions, idempotency, transactions, and audit.

Fourth, making the semantic platform the new transaction center. To make actions look "executable", migrating all business object states and write operations into the semantic platform often creates new dual-write and transaction consistency problems. Unless explicitly designed as the system of record for certain objects, the existing business system's transaction authority should be preserved.

Start with One Well-Bounded Action

Enterprises do not need to build action contracts for all APIs at once. A more feasible approach is to pick, in a scenario where semantic models and decision rules are already established, one action with clear object boundaries, controllable risk, and verifiable results.

Implementation can proceed in six steps:

Define the Action Type's business meaning, target object, expected effects, and necessary state transitions;

Associate decision, evidence, risk, permission, and human confirmation policies;

Map real business services, workflows, state queries, and failure handling mechanisms;

Design business idempotency key, execution state, receipt, and audit fields;

Publish the controlled capability via MCP tool or Tool API, not the raw write interface;

Validate with use cases: normal execution, unauthorized request, stale state, duplicate call, network timeout, parameter change after approval, and partial failure.

Whether this action can stop, diagnose, recover, or escalate to human in exceptional cases proves whether ontology intelligence is truly landed — more than a demo that simply calls an API once.

Summary

Action in ontology connects the semantic world with real business systems, but it is not a simple renaming of API.

Ontology and semantic models define the action's business meaning; the action contract links decisions, evidence, permissions, state transitions, and runtime implementations; MCP and API provide invocation entry points; the real business system remains responsible for transactions and final state.

Action in ontology is not a semantic wrapper around an API; it is a business execution contract that spans semantic, decision, permission, and transaction boundaries.