> For the complete documentation index, see [llms.txt](https://cerebral-systems.gitbook.io/cerebral-systems-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cerebral-systems.gitbook.io/cerebral-systems-docs/architecture/action-proposal-format.md).

# Action Proposal Format

Agents call `POST /v1/actions` before taking a side effect. The proposal is the security boundary: policy can only make strong decisions when the action is bounded and structured.

### Required Fields

| Field                  | Meaning                                                                            |
| ---------------------- | ---------------------------------------------------------------------------------- |
| `proposal_id`          | Caller-supplied idempotency key.                                                   |
| `actor.agent_id`       | Caller claim naming the agent requesting the action.                               |
| `summary`              | Human-readable action intent.                                                      |
| `action.target_system` | Registered actuator key, such as `kubernetes`, `github`, or `centaur.tool.deploy`. |
| `action.operation`     | Operation inside that actuator, such as `restart_service`.                         |
| `action.parameters`    | Operation-specific JSON object.                                                    |
| `risk.level`           | Caller risk claim: `low`, `medium`, or `high`. A reviewed catalog may raise it.    |
| `risk.blast_radius`    | Plain-language impact scope.                                                       |

Recommended fields:

| Field                  | Meaning                                                  |
| ---------------------- | -------------------------------------------------------- |
| `actor.run_id`         | Agent run, workflow, or trace id.                        |
| `actor.on_behalf_of`   | User or service account the agent represents.            |
| `action.rollback_plan` | How to recover from the action.                          |
| `risk.reversibility`   | `reversible`, `partially_reversible`, or `irreversible`. |
| `reasoning.evidence`   | Evidence the agent used before proposing the action.     |
| `confidence`           | Agent confidence from 0 to 1.                            |

### Example

```json
{
  "proposal_id": "deploy-001",
  "actor": {
    "agent_id": "langchain-worker",
    "run_id": "run-123"
  },
  "summary": "Restart checkout in staging",
  "action": {
    "target_system": "kubernetes",
    "operation": "restart_service",
    "parameters": {
      "service": "checkout",
      "environment": "staging"
    },
    "rollback_plan": "restart the previous checkout revision"
  },
  "risk": {
    "level": "medium",
    "blast_radius": "staging checkout traffic",
    "reversibility": "reversible"
  },
  "reasoning": {
    "evidence": ["checkout error rate is elevated", "pods are healthy but stale"]
  },
  "confidence": 0.82
}
```

### Idempotency

`proposal_id` is an idempotency key.

* Reusing the same `proposal_id` with the same body returns the original verdict.
* Reusing the same `proposal_id` with a different body returns a conflict.
* Retries must not duplicate actuator side effects.

Warrant passes `tenant_id:proposal_id` to idempotent actuators as the stable downstream idempotency key. The downstream provider must honor it for exactly-once external effects; Warrant cannot manufacture that guarantee around a non-idempotent API.

### Trusted versus claimed fields

The request body is not an identity or policy authority:

| Submitted value         | How Warrant treats it                                                                      |
| ----------------------- | ------------------------------------------------------------------------------------------ |
| `actor`, `on_behalf_of` | Preserved under `claims`; authoritative identity comes from the API key or hosted session. |
| `risk`                  | Preserved as a claim; `effective_risk` is at least the catalog minimum.                    |
| `requested_autonomy`    | Advisory only; policy decides whether approval is required.                                |
| `action.parameters`     | Valid only when they match the reviewed operation's closed JSON schema.                    |

Unknown operations, missing fields, extra fields, malformed values, and pinned MCP schema drift fail before policy evaluation in strict enforcement.

### Proposal design rules

* Make one proposal describe one bounded side effect.
* Put provider routing in `target_system` and `operation`, not in free-form text.
* Keep parameters machine-checkable and exclude credentials.
* Use a deterministic ID for retries of the same logical action, not for unrelated work.
* Describe blast radius and rollback in terms an approver can act on.
* Do not bundle a multi-step migration into one opaque operation unless the actuator makes that entire unit idempotent and auditable.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cerebral-systems.gitbook.io/cerebral-systems-docs/architecture/action-proposal-format.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.