Core concepts

Eda has a small, sharp vocabulary. Learn these six words and the rest of the docs read easily.

Action

An action is a single thing an agent wants to do: refund_customer, delete_user, send_email, deploy_service. You name it. An action carries:

agent — which agent is acting ("support-agent", "ops-bot"). Use "*"-friendly names; you’ll match on them in policies.
action — the verb, snake_case by convention.
params — the arguments that matter for the decision ({ amount, customerId }). Eda evaluates conditions against these and stores them in the audit log (sensitive keys are redacted first).
metadata — optional free-form context (request id, user id, source).

Every action you check gets a durable actionId you can look up later.

Decision

A decision is Eda’s answer to a check. decision.status is one of:

Status	Meaning	What your code should do
`approved`	Allowed — no policy blocked it (or a human approved).	Run the side effect.
`blocked`	A policy denied it outright.	Don’t run it; surface `decision.reason` to the model/user.
`pending`	A policy requires a human; nobody has decided yet.	Wait (`checkAndWait`) or return and poll later.
`denied`	A human explicitly denied it.	Don’t run it.

A decision also includes reason (human-readable), actionId, the matched policy (if any), and a risk score when AI scoring is on.

⚠️

Only approved is a green light. Treat everything else as “do not act.” The idiom is if (decision.status !== "approved") { … }.

Policy

A policy is a deterministic rule evaluated in the API on every check. A policy matches on agent + action (glob patterns) and optional conditions over params, and produces an effect:

allow — explicitly permit (useful to carve exceptions above a broad block).
block — deny outright → blocked.
require_approval — pause for a human → pending.

Policies have a priority; the highest-priority match wins. If nothing matches, Eda allows (fail-open by default at the policy layer — you decide the posture with a catch-all block if you want default-deny). Policies are evaluated in well under 10ms and never call a model. See Policies for globs, conditions, and the full operator list.

Approval

When a policy returns require_approval, the action becomes pending and shows up in the dashboard Approvals queue. A teammate approves or denies it (with an optional reason). That decision is recorded with the approver’s identity.

Your code learns the outcome one of two ways:

Inline — eda.checkAndWait(req, { timeoutMs }) blocks until a human decides or the timeout hits (EdaPendingTimeoutError).
Deferred — return now, persist the actionId, and later call eda.getDecision(actionId) or eda.waitForApproval(actionId) (e.g. from a webhook or a job).

Team members, roles, and the approval queue live in the dashboard.

Risk scoring (optional)

Beyond deterministic policies, Eda can score an action’s risk with a model, against a workspace risk threshold and natural-language instructions you set in Settings (e.g. “treat anything touching production billing as high risk”). When enabled, a high risk score can escalate an otherwise-allowed action to require_approval. Deterministic policies always run first and are authoritative; risk scoring is an additional safety net, not a replacement.

Audit log

Every check is written to an immutable audit log — allowed and blocked alike — with the agent, action, params, decision, matched policy, risk, approver, and timestamps. This is the system of record for “what did our agents do, and who let them?” Browse it in the activity feed, or pull it programmatically with eda.listActions() and the REST API.

Fail posture: open vs. closed

What happens if Eda is unreachable? You choose per-client with failMode:

failMode: "closed" (default) — if a check can’t complete, treat it as not approved. Safest: the action doesn’t run.
failMode: "open" — if a check can’t complete, allow it (availability over strictness). Use only where a missed gate is acceptable.

const eda = new Eda({ apiKey: process.env.EDA_API_KEY!, failMode: "closed" });

Where it runs

Policy evaluation runs at Eda’s edge/API (api.edahq.com) backed by a durable store. The SDK is a thin, retrying, zero-dependency client. You can also pre-filter locally with local rules to block the obvious cases without a network round-trip.

Quickstart Overview & reference