Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/joseluis-dev/harness-ai/llms.txt

Use this file to discover all available pages before exploring further.

The execution event is the canonical input contract for starting any harness action — from UI, n8n, external system, or document watcher. Every component that wants to invoke an agent or tool must produce an event that conforms to this schema. The event is persisted to the executions table before any processing begins, making it the immutable record of intent that the rest of the pipeline reacts to.

​
JSON Schema

{
  "source": {
    "type": "astro | n8n | external_system | watcher",
    "id": "string"
  },
  "actor": {
    "type": "user | system",
    "id": "string"
  },
  "intent": "string",
  "payload": {},
  "constraints": {
    "allow_cloud": false,
    "require_audit": true,
    "risk_level": "low"
  }
}

​
Fields

​
source

​
source.type
enum
required
Origin of the event. Allowed values:
  • astro — Harness Core UI (Telegram traffic routed through Harness Core also maps to astro).
  • n8n — signed webhook from an n8n automation workflow.
  • external_system — municipal system calling the harness directly.
  • watcher — document-detection pipeline that monitors for new or changed files.
​
source.id
string
required
Identifier for the originating source — a URL, webhook ID, or watcher node identifier. Used for correlation and audit trail linkage.

​
actor

​
actor.type
enum
required
The kind of principal driving the execution.
  • user — a physical person with a resolved institutional identity.
  • system — an automated process running without a human principal.
​
actor.id
string
required
Institutional ID of the actor. Resolved via mcp-identity-connector.get_user_context() before the event is created. For Telegram users, resolution maps telegram_user_id to the institutional identity.

​
Top-level fields

​
intent
string
required
Semantic description of the desired action (e.g. "query_sql_view", "generate_report"). The policy engine uses this field to determine which restrictions and approval flows apply. Intent strings should be short verb-phrases and are validated against the tool registry.
​
payload
object
required
Arbitrary, intent-specific data for the execution. The shape is free-form but is validated with Pydantic v2 (runtime) or Zod (BFF) against the schema registered for the given intent. Callers must not embed PII beyond what the intent schema permits.

​
constraints

​
constraints.allow_cloud
boolean
default:"false"
When false (the default), the harness will only route to local or self-hosted providers. Setting this to true is accepted only if the originating agent has an explicit policy entry (policy.cloud_allowed=true) and risk_level is low. Any true value without that policy results in POLICY_DENIED.
​
constraints.require_audit
boolean
default:"true"
When true (the default), the execution must generate audit_events rows throughout its lifecycle. Disabling audit requires an explicit policy exception; the default should not be overridden in production.
​
constraints.risk_level
enum
default:"low"
Determines the approval and audit posture for this execution. Allowed values: low, medium, high.
  • low — standard flow; no human approval required.
  • medium — elevated audit; no automatic human approval, but tooling may apply additional checks.
  • high — activates the human approval flow via approval_requests before the execution proceeds.

​
Default Constraints and What They Mean

The default constraint envelope — allow_cloud: false, require_audit: true, risk_level: "low" — directly encodes two non-negotiable architectural principles:
  • Local-first: all processing happens on institutional infrastructure unless a policy exception explicitly permits a cloud provider.
  • Full audit: every execution produces a traceable log of state transitions, tool calls, and actor decisions — no silent side effects.
Callers that omit the constraints object receive these defaults automatically. Overriding any default requires a deliberate decision and is subject to policy engine evaluation at runtime.

​
Immutability and Persistence Rules

An execution event is immutable once created. If the intent or payload needs to change, a new event must be created with a new execution_id. Any downstream correction is recorded as a new event linked to the original execution.
Setting constraints.allow_cloud=true without a matching policy.cloud_allowed=true entry in the tool registry will cause the execution to fail immediately with POLICY_DENIED. Never pass allow_cloud: true speculatively — configure the policy first.
constraints.risk_level="high" activates the human approval flow unconditionally. The execution will pause at waiting_approval status until an authorized approver accepts or rejects it via the approval interface. Plan for asynchronous completion when using this level.

​
Usage Rules Summary

  1. Every component that invokes an agent or tool must produce an event conforming to this schema — there is no alternative entry point.
  2. The event is persisted to the executions table before processing begins; the row exists even if a broker outage prevents immediate queueing.
  3. constraints.allow_cloud=true is accepted only when the originating agent has policy.cloud_allowed=true and risk_level is low.
  4. risk_level=high activates the approval_requests flow; execution does not proceed until a human approves.
  5. The payload field never contains stack traces, internal paths, container IDs, environment variable names, or raw SQL table names.

Build docs developers (and LLMs) love

Get started for freeTalk to us