Selah
docs

Integration guides by tenant type

Enterprise

This guide is for a company running its own AI agents and governing what they do and say. When the engine holds something for a human, the review happens inside Selah and your own team is the reviewer, with the full context and a summary in front of them.

Read Getting started and Agent Operating Procedures and the Shadow AOP Ledger first. Then follow these steps in order. Steps 1 to 6 are setup in the dashboard, where you author your AOPs. Steps 7 onward are the API integration.

Step 1. Create your tenant

In the dashboard, create your organization as a tenant and choose the type enterprise. The enterprise type gives you the guided setup wizard and routes every hold into your own review queue inside Selah.

The same can be done through the admin API; confirm the exact endpoint in the live OpenAPI. For setup, the dashboard is the simplest path.

Step 2. Register your agents

Register each agent you want to govern. Give it an identifier you will use in API calls, for example agent_sales_01, and set its mission and the topics it should stay away from. You will reference this agent_id in every data plane call.

Step 3. Choose which services to run

Turn on the checks you want, independently:

  • Input check, screens incoming messages.
  • Action check, governs what the agent does.
  • Response check, governs what the agent sends.

A service that is off does not run at all; the call passes through. Most enterprises start with the action check and the response check, since those carry the real liability.

Step 4. Author your AOPs

This is where you set the rules the engine will enforce. There are two parts.

Enable AOP packs. Turn on the versioned compliance and jurisdiction packs that match your industry and where you operate. They contribute AOPs at the correct precedence: compliance first, then jurisdiction, then agent type, then base, then campaign.

Author your own AOPs. On the policy and output configuration screens, set:

  • Action AOPs: which actions an agent may take and their limits, for example a refund ceiling.
  • Response AOPs, the source of truth the response check uses: banned phrases, prohibited claims, required disclaimers, allowed claims, and your price or discount catalog.

Step 5. Turn on shadow mode

Switch the tenant to shadow. In shadow, Selah computes every decision and records it to your Shadow AOP Ledger, but does not block anything. This is how you confirm the AOPs are right before they affect a live customer. Leave it on until the ledger shows the engine would block exactly what you want blocked.

Step 6. Generate an API key

On the API keys screen, generate an evaluate scoped key. This is the key your agent will use for the data plane. Store it as a secret in your environment, for example SELAH_API_KEY. Treat it like a password.

Step 7. Integrate the input check

When a message arrives, pass it to the input check before your agent engages. This is the lightest call and never blocks a real action.

curl -s https://api.selahcore.com/v1/gate/check \
  -H "X-API-Key: $SELAH_API_KEY" -H "Content-Type: application/json" \
  -d '{ "agent_id": "agent_sales_01", "text": "the incoming message", "context": { "thread_id": "th_42" } }'

def check_input(text, thread_id):
    r = requests.post(f"{BASE}/v1/gate/check", headers=HEADERS, json={
        "agent_id": "agent_sales_01", "text": text, "context": {"thread_id": thread_id},
    })
    r.raise_for_status()
    return r.json()  # {"decision": "allow" | "deny", ...}

Step 8. Integrate the action check

This is the most important call. Before your agent does anything that touches money, data, or a system, send the proposed action to the engine and act only on a permit. The engine resolves your action AOPs and returns the verdict.

curl -s https://api.selahcore.com/v1/evaluate \
  -H "X-API-Key: $SELAH_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_sales_01",
    "action": "process_refund",
    "parameters": { "amount": 4200, "currency": "USD", "order_id": "A-7781" },
    "context": { "idempotency_key": "evt_4f3a", "user_ref": "cust_991" }
  }'

def evaluate_action(action, parameters, idempotency_key, user_ref=None):
    r = requests.post(f"{BASE}/v1/evaluate", headers=HEADERS, json={
        "agent_id": "agent_sales_01",
        "action": action,
        "parameters": parameters,
        "context": {"idempotency_key": idempotency_key, "user_ref": user_ref},
    })
    r.raise_for_status()
    return r.json()  # {"decision": "permit"|"hold"|"deny", "decision_id": "...", "reason": "..."}

decision = evaluate_action(
    "process_refund",
    {"amount": 4200, "currency": "USD", "order_id": "A-7781"},
    idempotency_key="evt_4f3a",
)
if decision["decision"] == "permit":
    do_the_refund()           # proceed
elif decision["decision"] == "hold":
    wait_for_human(decision)  # see step 10
else:
    inform_customer_politely()  # denied, do not act

Keep the decision_id from a permit. If you execute the action through a Selah connector rather than in your own code, you will pass that decision_id to prove the action was permitted. See step 11.

Step 9. Integrate the response check

Before your agent sends a reply to a customer, validate it against your response AOPs. Send the conversation thread in context so the model layer can judge whether the reply is grounded in what the agent actually knows.

curl -s https://api.selahcore.com/v1/validate/output \
  -H "X-API-Key: $SELAH_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_sales_01",
    "response_text": "Sure, I can give you 30% off and free delivery.",
    "context": { "thread": [ {"role":"user","text":"any discount?"}, {"role":"agent","text":"let me check"} ] }
  }'

def validate_response(text, thread):
    r = requests.post(f"{BASE}/v1/validate/output", headers=HEADERS, json={
        "agent_id": "agent_sales_01", "response_text": text, "context": {"thread": thread},
    })
    r.raise_for_status()
    return r.json()  # {"decision": "allow"|"block"|"escalate", "reason": "...", "flagged": ...}

verdict = validate_response(candidate_reply, thread)
if verdict["decision"] == "allow":
    send_reply(candidate_reply)
else:
    hold_reply(verdict)  # blocked or escalated; a human reviews in Selah

In shadow mode this returns the real verdict but never asks you to withhold the reply, so the Shadow AOP Ledger captures what it would have done while you calibrate.

Step 10. Handle holds in your review queue

When the engine returns hold, or a response escalates, the item appears in your review queue inside the Selah dashboard, with the full context and a plain language summary. A person on your team approves or rejects it. You also receive an email if you turned on the hold and escalation notifications.

To react programmatically, register a webhook so your systems know when something was held and when it was resolved. See Webhooks and holds. The two events you care about are action.held and review.resolved.

Step 11. Execute permitted actions through a connector, optional

If you want the zero credential guarantee to extend all the way to execution, register an HTTP connector in the dashboard for the system the agent acts on, and store its credentials there. The agent never sees them. Then execute a permitted action by passing the decision_id from the permit:

curl -s https://api.selahcore.com/v1/connectors/$CONNECTOR_ID/execute \
  -H "X-API-Key: $SELAH_API_KEY" -H "Content-Type: application/json" \
  -d '{ "decision_id": "dec_01H", "payload": { "order_id": "A-7781", "amount": 4200 } }'

The engine verifies the decision is a permit for your tenant and matches the action, then makes the outbound call server side with the stored credentials. A repeat with the same idempotency key returns the prior result and does not fire twice.

Step 12. Calibrate, then enforce

Run in shadow for a few days and read your Shadow AOP Ledger in the audit view. Adjust your AOPs until what Selah would block matches what you actually want blocked. When the AOPs are right, turn enforcement on. Now the engine stops the bad action or response for real and holds the gray areas for your team. See Going live.

A worked example

A dealership runs agent_sales_01. A customer pushes for a deal and the agent drafts: "Sure, I can give you 30% off the Hilux and free delivery this week." Your catalog has no such discount, and you have a response AOP that forbids quoting outside the catalog. The response check blocks it before it is sent. Because you are an enterprise tenant, the item lands in your review queue with the conversation and a summary, your sales lead is emailed, and they decide. The customer never saw a promise you cannot keep.

Later the agent proposes a refund of 4,200 when the AOP limit is 1,000. The action check returns hold. Nothing is refunded. A manager approves or denies it in the dashboard, and you have a clean record of who decided and why.

Checklist

  • Tenant created as type enterprise, agents registered.
  • Services chosen, AOP packs enabled, your own action and response AOPs authored.
  • Shadow mode on, evaluate scoped API key stored as a secret.
  • Input, action, and response calls integrated.
  • Review queue owner assigned, hold and escalation notifications on.
  • Connectors registered if you execute through Selah.
  • Calibrated against the Shadow AOP Ledger, then switched to enforcement.