Canonical Operation Contract

Source of truth

The canonical business-system input is the bundled standard_system_operation.schema.json. The Agent Prompt routes in-scope requests to this Skill, and this Skill returns a wrapper around exactly one operation. A host may replace the bundled schema only by an explicitly versioned compatible contract.

{
  "status": "agent_parse_passed",
  "blockers": [],
  "operation": {
    "action": "team_order_create",
    "order_nature": "test",
    "submit_mode": "dry_run",
    "data": {}
  }
}

For blocked input:

{
  "status": "agent_parse_blocked",
  "blockers": ["missing_field:data.product"],
  "operation": null
}

The Skill must return JSON only. The business system preserves raw text, task ID, external session ID, and parser/profile metadata outside operation.

Allowed operation keys

At the operation level, use only:

action
order_nature
submit_mode
source (only schema-declared metadata)
data

At the data level, use fields declared in the standard schema: customer/product/route/trip/order number, dates, recurrence, capacity, counts, prices, users, logistics, requests, passenger list, attachments, existing references, updates, confirmation, recovery, defaults, validation notes, and resolution. The current runtime also consumes the two documented compatibility fields order_mode and test_marker; do not add other ad-hoc fields.

Two-stage resolution

For team create and batch tasks, the Agent may return a task-ready operation without customer, route, trip, or order_number when those values are ERP-derived. It must then include:

"resolution": {
  "mode": "task_ready",
  "deferred_fields": ["customer", "route", "trip", "order_number"]
}

If all four fields are already present, still use "mode": "task_ready" unless the host has supplied verified ERP lookup evidence. The ERP preflight may call the product-template side effect and exact lookups to complete these fields. Only a fully resolved operation may be treated as erp_ready; neither state claims that an ERP write occurred.

Do not add routeName, originalText, task_id, session_id, parser_prompt_version, credentials, selectors, or arbitrary model commentary to operation. Transport metadata belongs in the business task wrapper.

Status rules

agent_parse_passed requires operation and an empty blockers array.
agent_parse_blocked requires a non-empty blockers array and operation: null.
Missing user-owned facts, ambiguous business references, conflicting explicit values, unsupported actions, or unsafe input must be blocked. ERP-owned deferred fields are valid only when represented by resolution.

Compatibility boundary

The handoff package's erp-task-v1 envelope is useful for internal Skill/executor interoperability. Its operation=create_order, route=team_single, and task.fields shape is not the Agent output contract. If the Skill receives that legacy shape, normalize it internally into the seven-action standard operation; do not ask the cloud Agent to emit both formats.

3.1 KiB Raw Permalink Blame History