Proposal Envelope Schema for AI Agents

A proposal envelope schema is a structured contract an AI agent emits before any external side effect. It captures actor, goal, target system, exact action, affected record, evidence, risk class, approval owner, expiry, idempotency key, rollback path, state re-checks, policy decision, and log destination so the business can review, approve, execute, and audit the action.

Business agents need a format that separates thinking from execution. The agent can analyze a thread, inspect a record, draft a reply, or recommend a next step. But before the system sends, updates, posts, refunds, invites, deletes, or changes a live record, the action should become a reviewable object.

That object is the proposal envelope. The schema below is the practical version: specific enough for policy checks, approval inboxes, workflow execution, and audit logs, but simple enough for a small team to use before the architecture becomes heavy.

The execution chain

The schema belongs between agent reasoning and tool execution.

agent reasoning -> proposal envelope -> policy decision -> approval inbox -> state re-check -> execution -> evidence log

This chain matters because it gives each layer a distinct responsibility. The agent prepares a proposal. The policy layer classifies it. A reviewer approves or rejects it when needed. The workflow re-checks current state before executing. The workspace logs what happened and why.

Without that separation, teams end up approving vague AI output instead of concrete business actions. A human sees a summary, a Slack message, or a draft, but not the exact record, risk class, expiry rule, duplicate prevention key, or evidence that made the action acceptable.

Minimum viable schema

A useful first schema does not need to model every enterprise permission system. It needs to answer seven questions reliably:

1. Who or what proposed this action?
2. Which business goal does it serve?
3. What exact side effect will happen?
4. Which evidence supports the proposal?
5. Which policy rule applies?
6. What must still be true at execution time?
7. Where will the final result be logged?

If those answers travel with the action, review becomes operational instead of conversational. The reviewer can approve an action contract, not a loose suggestion.

Recommended fields

The proposal envelope should include fields that support policy checks, human review, workflow handoff, and future debugging.

• schema_version: the contract version, so older proposals can still be interpreted.
• proposal_id: a stable identifier for the proposed action.
• created_at: when the proposal was generated.
• actor: the agent, workflow, schedule, user, or skill that created the proposal.
• goal: the active business goal loop the action is meant to advance.
• target_system: the system that will be changed, such as CRM, Gmail, billing, calendar, Slack, Discord, file storage, or a database.
• action: the exact operation and payload the workflow intends to execute.
• affected_record: the customer, lead, invoice, ticket, account, project, message, or document touched by the action.
• source_evidence: the cited records, messages, documents, policies, or notes used to justify the proposal.
• risk_class: a business-defined class such as low, review, sensitive, blocked, or custom.
• policy_decision: allow, require_approval, deny, escalate, or needs_context.
• approval: owner, status, expiry time, and reviewer notes.
• state_rechecks: conditions that must remain true immediately before execution.
• idempotency_key: a deterministic key that prevents duplicate sends or updates.
• rollback: what can be undone, what cannot, and which mitigation path exists.
• log_destination: where the proposal, decision, execution result, and evidence should be recorded.

JSON example

This example shows a proposal envelope for a customer-facing renewal follow-up. The agent is allowed to prepare the work, but the policy check requires account-owner approval before sending.

{
  "schema_version": "2026-08-26",
  "proposal_id": "pe_01J9_RENEWAL_4821",
  "created_at": "2026-08-26T16:42:00-07:00",
  "actor": {
    "type": "agent",
    "id": "renewal_followup_agent",
    "skill": "account_retention_followup_v3"
  },
  "goal": {
    "id": "goal_reduce_renewal_risk",
    "name": "Recover at-risk renewals",
    "owner": "account_ops"
  },
  "target_system": {
    "name": "gmail",
    "operation": "send_email"
  },
  "action": {
    "type": "external_message",
    "recipient": "[email protected]",
    "subject": "Next step for your renewal review",
    "body_draft": "Thanks for the context. Based on the support notes, here is the cleanest next step..."
  },
  "affected_record": {
    "type": "account",
    "id": "acct_4821",
    "name": "Example Customer"
  },
  "source_evidence": [
    {
      "type": "support_ticket",
      "id": "ticket_19033",
      "summary": "Customer reported onboarding delay and asked for a renewal plan."
    },
    {
      "type": "crm_note",
      "id": "crm_note_771",
      "summary": "Account owner approved retention offer language but not discount terms."
    },
    {
      "type": "policy_doc",
      "id": "renewal_policy_2026",
      "summary": "Service commitments require account-owner approval."
    }
  ],
  "risk_class": "review",
  "policy_decision": {
    "status": "require_approval",
    "reason": "Customer-facing message references a service commitment."
  },
  "approval": {
    "owner_role": "account_owner",
    "status": "pending",
    "expires_at": "2026-08-27T16:42:00-07:00"
  },
  "state_rechecks": [
    {
      "condition": "customer_has_not_replied_since_proposal",
      "source": "gmail_thread"
    },
    {
      "condition": "renewal_status_is_still_at_risk",
      "source": "crm_account"
    },
    {
      "condition": "no_duplicate_followup_sent",
      "source": "activity_log"
    }
  ],
  "idempotency_key": "gmail_send:acct_4821:renewal_followup:2026-08-26",
  "rollback": {
    "reversible": false,
    "mitigation": "Log correction and create account-owner follow-up task if message is sent in error."
  },
  "log_destination": {
    "type": "workspace_activity_log",
    "record": "acct_4821"
  }
}

The exact property names can vary by product. The important point is that the business action has a stable contract. Policy checks and approvals should inspect the same object that execution will use.

Policy outcomes

The schema should support more than approve or reject. Business workflows need several outcomes:

• allow: the action is low risk, reversible, inside the agent's scope, and supported by enough evidence.
• require_approval: the action is useful but touches a customer, money, permissions, public channels, legal wording, pricing, or trust-sensitive context.
• deny: the proposal is outside tool scope, lacks evidence, violates a policy, targets the wrong record, or attempts a blocked action.
• escalate: the action needs a named person, such as founder, manager, account owner, finance, legal, or security.
• needs_context: the workflow cannot decide because the source set is stale or incomplete.

The policy reason should be short and visible. Reviewers should not have to guess whether the agent paused because of money movement, missing evidence, public visibility, customer tone, or a stale CRM record.

State re-checks are part of the contract

The approval should not mean "send this later no matter what." It should mean "this action is approved only if these facts are still true at execution time."

That is why state re-checks belong inside the proposal envelope instead of being buried inside a workflow. The reviewer should see the assumptions that will be tested before the action runs.

Common state re-checks include:

• The customer has not replied after the proposal was created.
• The affected record has not been changed by another workflow.
• The approval has not expired.
• The source evidence is still current enough for the action.
• The account, invoice, ticket, or opportunity is still in the expected state.
• The idempotency key has not already been executed.

This is where many agent systems fail in real operations. They can create a good action at 10:00, but the action is wrong by 10:17 because the business state changed. A workspace for business agents needs to treat state as part of the approval contract.

Idempotency prevents duplicate business actions

Retries are normal in software. Duplicate business actions are not harmless.

A retry can send the same follow-up twice, create duplicate CRM tasks, invite the same user again, apply a refund twice, update the wrong lifecycle stage, or post the same message publicly. A proposal envelope should carry an idempotency key for every action that leaves a visible trace.

For a small team, the key does not need to be complex. It can combine target system, operation, affected record, goal, and date. The important rule is that execution must check the key before taking the action and write the key to the log after execution.

How the approval inbox should display it

An approval inbox should not show a raw JSON blob by default. It should turn the proposal envelope into a compact review item:

• Action: what will happen.
• Target: which system and record will change.
• Reason: why the agent proposed it.
• Evidence: the cited records or policies.
• Risk: the policy classification.
• Reviewer: who can approve it.
• Expiry: when approval stops being valid.
• Re-checks: which facts will be verified before execution.
• Log: where the decision and result will be recorded.

The full envelope should still be available for inspection. But the default review surface should help a human make a fast, defensible decision without opening five separate tools.

Where workflow tools fit

Workflow builders are strongest when the process is deterministic: triggers, webhooks, transformations, retries, routing, queue handling, and execution. The AI business workspace is strongest when the process needs context, judgment, policy checks, human review, and operating memory.

The practical split is:

workflow trigger -> workspace context -> agent proposal -> policy decision -> approval -> workflow execution -> activity log

That model does not require the workspace to replace workflow tools. It gives the AI step a contract before a workflow tool executes the side effect. For small teams, this is the difference between automating faster and operating with control.

Manor AI's platform direction includes compatibility with n8n-style workflows so deterministic automation can connect to agents, reusable skills, approvals, citations, and logs inside an AI business workspace.

Implementation checklist

1. Define which tool actions require a proposal envelope.
2. Give each agent and reusable skill a stable actor identifier.
3. Map every proposal to a business goal loop.
4. Require cited evidence for customer-facing, financial, public, permission, or legal-adjacent actions.
5. Classify every proposal with a policy outcome and reason.
6. Set expiry times for approvals.
7. Attach state re-checks before execution.
8. Use idempotency keys for sends, updates, refunds, invites, posts, and task creation.
9. Log the proposal, decision, reviewer, execution result, and evidence trail.
10. Measure the loop by recovered work, reduced review time, fewer stale actions, and cleaner auditability.

How Manor AI uses this pattern

Manor AI is designed around the idea that useful business AI runs inside reviewable goal loops. A goal loop needs agents and reusable skills, but it also needs workspace context, policy checks, approval gates, state re-checks, idempotency, citations, logs, and measurement.

The proposal envelope schema is one practical operating contract for that model. It makes the agent's next step inspectable before it becomes a side effect. It also gives the workspace a shared object for approval, execution, and later audit.

For the surrounding concept, read Policy Checks for AI Agents. For the recurring operating model, read How to Handle Goal Loops in Business Operations With AI Agents. For examples by business type, use the AI Agent Workflow Library. For approval design, see Approval Gates and Activity Logs.