68 lines
3.1 KiB
Markdown
68 lines
3.1 KiB
Markdown
# Canonical Operation Contract
|
|
|
|
## Source of truth
|
|
|
|
The canonical business-system input is the bundled [standard_system_operation.schema.json](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.
|
|
|
|
```json
|
|
{
|
|
"status": "agent_parse_passed",
|
|
"blockers": [],
|
|
"operation": {
|
|
"action": "team_order_create",
|
|
"order_nature": "test",
|
|
"submit_mode": "dry_run",
|
|
"data": {}
|
|
}
|
|
}
|
|
```
|
|
|
|
For blocked input:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
"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.
|