Documentation quickstart

Five steps, ending with a governed action and the record of why it was allowed. Nothing here builds an AI system — step 2 registers one that already exists, which is the shape every OpsAI integration takes.

This is the conceptual path and it assumes you already have an account. If you need an organization and an API key first, the developer quickstart covers the setup and ends on a refusal rather than a success.

Before you start

You need an API key and one system you are willing to let an action reach. A sandbox tenant is the sensible choice for the first pass: every step below is reversible, but step 4 is a real evaluation against a real policy and step 5 files a real record.

npm install @opsai/sdk

export OPSAI_API_KEY="sk_test_..."

1. Connect a system

A connection is OpsAI’s credential-holding relationship with a system of record. The credential is held centrally and never handed to an AI system — an agent receives a scoped, short-lived grant derived from it, which is what makes the agent never sees the API key a fact rather than an aspiration.

import { OpsAI } from '@opsai/sdk';

const opsai = new OpsAI({ apiKey: process.env.OPSAI_API_KEY });

const connection = await opsai.connections.create({
  system: 'Razorpay',
  // Held by OpsAI. Nothing downstream ever receives this value.
  credential: { kind: 'api_key', value: process.env.RAZORPAY_KEY },
  // The actions this connection is permitted to carry out at all.
  allows: ['issue.refund', 'payment.read'],
});

console.log(connection.id); // conn_razorpay_live

2. Register the AI system

Register the thing that will be proposing actions. The framework field is descriptive and nothing branches on it; what matters is the accountable human and the actions the system is allowed to attempt.

const agent = await opsai.agents.create({
  id: 'refund-resolver',
  // Descriptive only. OpsAI governs at the boundary, not inside your control flow.
  framework: 'langgraph',
  model: 'claude-sonnet',
  // Required. An AI system with no accountable human cannot be governed.
  owner: 'priya@acme.internal',
  attempts: ['issue.refund'],
});

3. Write a policy

A policy is written in business terms and compiles to a bound — a rule evaluated with no model call in the path. This is the real refund ceiling from the sample estate, owned by Finance at version v7.

# what a refund may be — not what a model may say
bound issue.refund {
  amount     <= INR 25_000
  scope      == order.placed_by(request.subject)
  requires   order.status in ["delivered","cancelled"]
  rate       <= 5 / hour / agent
  on_exceed  deny + escalate(owner)
}

Two things about that source are load-bearing. It is owned by the team that carries the risk rather than by a platform team, and it is versioned — so an action can be replayed later against the version that was in force when it happened, not against whatever the rule says today.

4. Evaluate an action

Now the loop. Your AI system proposes an action; OpsAI decides before it reaches Razorpay.

const decision = await opsai.actions.evaluate({
  agent: 'refund-resolver',
  action: 'issue.refund',
  subject: 'ORD-40122',
  target: 'Razorpay',
  amount: { currency: 'INR', value: 18400 },
});

if (decision.outcome === 'authorized') {
  // The grant is scoped to this action and expires with it.
  await razorpay.refunds.create({ ... }, decision.grant);
}

The outcome is one of three. authorized means proceed and the grant is attached. held means a person has to decide, and the hold expires rather than queueing — the default outcome of nobody responding is no. denied means a check failed, and the response names which one.

5. Read the trace

This is the step the previous four exist for. A trace is the six stages of an attempt with the rule version, the checks that ran and the authority chain — and it exists whether the action was allowed or refused.

curl https://api.opsai.dev/v1/actions/ACT-7512/trace \
  -H "Authorization: Bearer $OPSAI_API_KEY"

What comes back is not a log line. It is the request, the identity that made it, the authority chain from the accountable human down to the acting system, the policy evaluation with each check and its result, the decision, and the sealed evidence reference. Nobody assembles it afterwards, which is why it is complete.

Where to go next

Core concepts defines the vocabulary the rest of the documentation assumes, and it is the right next page if you plan to write policies. Governance covers policy syntax and lifecycle properly, and the API reference has every endpoint with its errors and SDK equivalent.