Write an AI agent approval workflow as an open-source policy file

The four parts of an approval workflow

A rule decides which call waits. A record holds that call while it waits. A person decides it. A log keeps the call and the decision together.

Most write-ups cover the person and stop there. That leaves the binding unstated, and the binding is what separates a control from a speed bump. A reviewer handed "the agent wants to send an email" has one sensible response, and it is not Deny. A reviewer handed the recipient, the subject and the account can judge the send.

Kortix puts the first two parts in the project repo. The rule is a policy file. The record is an execution_id on a call that returned 202 and ran nothing. The third part is a person with authority over the project, and the fourth is the audit trail that keeps both.

This is the split that decides most oversight arguments: the decision is made per action, not per system. Human in the loop names the person in front of the call, and the workflow is the machinery that puts them there.

The rule is a file, and the order is the design

A policy decides what happens when an action is called: Allow (always_run), Ask (require_approval) or Block (block). Kortix reads four layers in order and stops at the first match:

1. 1Project-wide policies: in kortix.yaml.
2. 2The connector's own policies:.
3. 3sensitive: true on the connector.
4. 4policy.default_mode.

No connector rule overrides a project rule. Company-wide lines therefore belong in the file, where they arrive as a diff someone can read.

policy:
  default_mode: risk

policies:
  - match: gmail.send_email
    action: always_run
    conditions:
      - arg: to
        match: "*@example.com"
  - match: gmail.send_email
    action: require_approval

policy.default_mode: risk sets the floor. Reads run. Writes and destructive actions are held. That one line is a working workflow on its own, because it decides every action the rules do not name. Approval gates you set. Off until you set them. A file with no policy: block falls back to allow_all, which runs every unmatched action.

The first rule allows gmail.send_email when to matches *@example.com. The second holds every remaining gmail.send_email. Two rules, one action, and the only difference between them is an argument.

Order carries the meaning. The first match wins, so the narrow allowance has to come first. Reverse the two rules and the general one matches every send, internal recipients included, and the allowance never runs. Reading a policy file is mostly reading it in order.

The rest of the condition syntax follows the same logic. arg is a dot path into the arguments, so message.channel reaches a nested field. A rule holds up to 10 conditions, and all must match. negate: true inverts one. A missing argument never matches the pattern, which is why a negated condition on an absent argument holds instead of passing. A malformed condition fails closed, so a typo narrows the gate rather than opening it. Patterns are globs, case-insensitive, or /regex/ in slashes.

The same three settings are reachable from a terminal: kortix connectors policy set --default risk --apply, kortix connectors policy add "gmail.send_*" ask --condition to='*@example.com', and kortix connectors policy gmail set send_email block.

What the approver is shown, and what one approval covers

Nothing runs. The call comes back 202, carrying status: "pending_approval", approval_url, approval_summary and execution_id, and that payload is what the person acts on.

The person opens the call in Review → Needs you, through approval_url, or on the approval card in a Slack or Teams thread. The page shows the redacted arguments the provider will receive, and the choice is Approve or Deny, with an optional message back to the agent. Redaction earns its place here: the reviewer decides on the arguments themselves rather than on a sentence the agent wrote about them.

The scope is one exact request: the same connector, action, arguments and account, and a changed argument needs a new approval. That rule is the difference between a decision and a nod in the direction of oversight. An approval that covers a class of future calls has already decided them, and the reviewer learns within a week that their answer does not depend on what they read.

After an approval, the identical call runs once when it repeats within 15 minutes. A retry loop therefore costs one decision, not fifteen.

A held call expires when nobody decides it within 24 hours, or within the project's approvals.ttl. approval_url expires at the same time, the card shows Expired, and the session does not resume. The agent asks again with a new call. Expiry is what keeps the queue a list of decisions instead of a list of messages.

There is no session-wide approval. An action that must run unattended needs an Allow rule. A project manager or the person who started the session decides a held call, and a session started with an API token is decided by project managers only.

A week of approvals shows which rules earn their place

Every action is recorded. Reading, exporting and streaming the audit log depend on the plan. Read one week of held calls and count three things.

Approvals that arrived unchanged. When nearly every held call is granted as written, the rule is drawing a line the work never crosses. Move that action to an Allow rule, or narrow the condition until the queue holds only the calls a person can actually improve.

Calls that expired. An expiry means nobody with authority opened it, or nobody could tell what they were approving. Both are routing problems. Change the approver or the summary, not the agent.

Rules that never matched. Project rules use fully qualified names, so an action renamed upstream leaves a rule pointing at nothing. A rule shadowed by an earlier match looks identical from the log: silent. Both are cost-free to delete and expensive to trust.

The number worth reporting is how many approvals changed on the way through, not how many were granted. A queue that grants everything, on identical arguments, week after week, is a formality, and the people in it know that before the audit does.

The code path runs the same gate

Session work reaches main through a change request. Merge is default-deny for agents.

The four parts repeat there. The rule is the merge gate. The record is the change request with its diff. The person is the reviewer. The log is the change request history and the audit trail.

Both mechanisms belong on one page because they make the same request of a person: read the actual change, then decide. A team that reviews a connector rule as a diff and then clicks through every email approval has built one control and one form, and only the diff is doing work. Human on the loop is where the second half of that habit gets tested, and how to choose sorts a single action into hold, supervise or allow.