Selah
docs

Integration guides by tenant type

Private deployments

This guide is for a private agent, often self hosted, that acts on its own. It is the lightest path. When the engine needs a human, it raises an alert in the Selah panel and sends an email, and the Selah dashboard is your control surface, so you do not have to build one.

An honest note on self hosted runtimes: today Selah provides the engine, a software development kit, and guardrail middleware you put in front of the agent. Deeper, runtime specific adapters are on the roadmap and are not available yet. What you integrate now is the middleware pattern and the API calls below.

Read Getting started and Agent Operating Procedures and the Shadow AOP Ledger first. Steps 1 to 5 are setup. Steps 6 onward are the integration.

Step 1. Create your tenant

In the dashboard, create your tenant of type private. The private type gives you the quickstart surface and routes holds to the Selah panel plus email.

Step 2. Register your agent

Register the agent with an identifier, for example agent_ops_01, and set its limits. You will use this agent_id in every call.

Step 3. Choose which services to run

For a private agent that acts autonomously, the action check is the one that matters most, since that is where an unattended agent can do real damage. Turn on the input and response checks if the agent also talks to people.

Step 4. Author your AOPs

Set the rules the engine will enforce: the action AOPs that define the actions the agent may take and their limits, and, if it sends messages, the response AOPs on the output configuration screen. Enable any compliance or jurisdiction packs that apply.

Step 5. Turn on shadow and get a key

Switch the tenant to shadow so the engine builds a Shadow AOP Ledger of what it would do without blocking anything. On the API keys screen, generate an evaluate scoped key and store it as a secret, for example SELAH_API_KEY.

Step 6. Put the middleware in front of your agent

Rather than acting directly, your agent proposes actions and responses through Selah and acts only on a permit. The pattern is a thin wrapper around the action it wants to take.

import os, requests

BASE = "https://api.selahcore.com"
HEADERS = {"X-API-Key": os.environ["SELAH_API_KEY"], "Content-Type": "application/json"}

def guarded_action(action, parameters, idempotency_key):
    """Propose an action, act only if the AOPs permit it."""
    d = requests.post(f"{BASE}/v1/evaluate", headers=HEADERS, json={
        "agent_id": "agent_ops_01",
        "action": action,
        "parameters": parameters,
        "context": {"idempotency_key": idempotency_key},
    }).json()

    if d["decision"] == "permit":
        return run_action(action, parameters)      # safe to proceed
    if d["decision"] == "hold":
        raise PendingApproval(d)                    # alert is in the Selah panel and email
    raise Denied(d)                                 # must not act

Step 7. Integrate the action check

This is the call that protects you. Send every consequential action through it before it runs, and the engine resolves your action AOPs.

curl -s https://api.selahcore.com/v1/evaluate \
  -H "X-API-Key: $SELAH_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_ops_01",
    "action": "bulk_update_records",
    "parameters": { "scope": 1800 },
    "context": { "idempotency_key": "run_55" }
  }'

A permit proceeds, a hold waits for you, a deny stops. The agent keeps working on everything within its limits; only the out of bounds action waits.

Step 8. Integrate the response check, if the agent talks to people

Same as the other paths, against your response AOPs. Send the conversation thread so the model layer can judge grounding.

def guarded_reply(text, thread):
    v = requests.post(f"{BASE}/v1/validate/output", headers=HEADERS, json={
        "agent_id": "agent_ops_01", "response_text": text, "context": {"thread": thread},
    }).json()
    if v["decision"] == "allow":
        return send(text)
    raise HeldReply(v)  # alert in the Selah panel and email

The input check, if you use it, is POST /v1/gate/check, as in Getting started.

Step 9. Point alerts at the right person

When something is held, an alert appears in your Selah panel and an email is sent. Make sure the panel and email notifications point at whoever should see a hold quickly, and check the panel on a rhythm so a held item does not stall. With a small team this habit matters more than any automation.

Step 10. Execute permitted actions through a connector, optional

If you want the agent to never hold credentials at all, register an HTTP connector in the dashboard for the system it acts on, store the credentials there, and execute permitted actions 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": { "batch": "nightly-55" } }'

The engine executes server side with the stored credentials, only against a real permit, and an idempotency key keeps a retry from acting twice.

Step 11. Calibrate, then enforce

Run in shadow, read the Shadow AOP Ledger to confirm the limits are right, then turn enforcement on. Keep enforcement on for the hard limits you are sure about, and keep the judgment calls in shadow until you trust them. See Going live.

A worked example

An internal operations agent can update records. You have an action AOP that limits it to 200 records per run. It decides to change 1,800 in one run. The action check returns hold before anything changes. An alert appears in your Selah panel and an email lands in your inbox. You open the held item, see the action and the reason, and approve or reject it. Everything within the limit kept running the whole time.

Checklist

  • Tenant created as type private, agent registered with its limits.
  • Action AOPs authored, response AOPs too if it talks to people.
  • Action check integrated through middleware, response check where needed.
  • Shadow on, evaluate scoped key stored as a secret.
  • Panel and email alerts pointed at the right person.
  • Connectors registered if you want zero credentials in the agent.
  • Calibrated against the Shadow AOP Ledger, hard limits enforced, judgment calls left in shadow until trusted.
  • Roadmap noted: deeper runtime adapters are not available yet; use the middleware and API today.