Agent exposure

By the end of this page you will have exposed an agent on an installed appliance and called it with an API key.

An appliance has no Studio, so exposure is set in one file on the install host: config/api-keys.yaml. The gateway re-reads it within about 5 seconds of a save, so exposing an agent, adding a key or revoking one never needs a restart.

Prerequisites

• An installed, running appliance. See Installing it.
• Shell access to the install host, in the archive folder.
• Model credentials in .env. The appliance never carries qRaptor’s model credentials, so an AI agent or multi-agent system can’t answer until you add your own provider’s key. See Connecting models.
• The roles your agents’ data needs. A key acts with the roles you give it, and only sees the tables those roles can read. See Give the key a role.

How it works

A call goes through only when both of these allow it:

Keys only reach agent, multi-agent system and conversation endpoints — never your app’s own /api routes.

Find your agents’ endpoints

Each export lists the endpoints of every agent and system it carries, with their IDs:

• Studio — the export’s API access tab on the project’s Appliance page.
• The archive — the API access section of README.md.

Expose an agent

KEY="qr_$(openssl rand -hex 24)"
echo "$KEY"

exposed:
  agents:
  - id: 3f6c2a10-7d4e-4b8a-9c21-5e0f8a7b6d34
    name: Order Details Agent
    type: task_agent
    enabled: true

keys:
- name: order-portal
  key: qr_your_generated_key
  scopes: [invoke, "runs:read", "info:read"]
  roles: [admin]
  restrict_to:
  - 3f6c2a10-7d4e-4b8a-9c21-5e0f8a7b6d34
  enabled: true

docker compose logs gateway --since 1m | grep appliance_api

curl -sS -X POST "https://apps.example.com/agents/3f6c2a10-7d4e-4b8a-9c21-5e0f8a7b6d34/run" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "agent_id": "3f6c2a10-7d4e-4b8a-9c21-5e0f8a7b6d34",
        "variables": { "order_id": "0b9e7d21-4c3a-4f5e-8a6b-7c1d2e3f4a5b" },
        "execution_mode": "production"
      }'

Give the key a role

An agent reads your app’s data as the key that called it. The key’s roles decide which tables it can see, with the same data governance rules your app’s users get — the permissions you set in Studio under your app’s security travel with the export.

A key with no roles acts as guest. If guest can’t read a table, the agent can’t either: it reports the table doesn’t exist, finds no rows, or gives a vague answer — the call itself still returns 200.

To fix it, give the key a role that can read what the agent needs:

- name: order-portal
  key: qr_your_generated_key
  scopes: [invoke, "runs:read", "info:read"]
  roles: [admin]

Choose the narrowest role that works. A key with admin reads everything admin can — for a public-facing integration, prefer a role limited to the tables it needs.

Request examples

Every request sends Authorization: Bearer qr_…. Set BASE to your QR_PUBLIC_URL.

AI agent — ask once:

curl -sS -X POST "$BASE/agents/$AGENT_ID/run" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"message": "fetch me orders placed by jane.doe@example.com", "input_variables": {}}'

AI agent — streamed (-N shows events as they arrive):

curl -sS -N -X POST "$BASE/agents/$AGENT_ID/stream" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"message": "fetch me orders placed by jane.doe@example.com", "input_variables": {}}'

AI agent — conversation. Start with session_id: null, then send back the sessionId from the response as session_id on each next message:

curl -sS -X POST "$BASE/agents/$AGENT_ID/conversation" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"message": "Hello", "session_id": null, "input_variables": {}}'

Task Agent — a run’s result and trace (run ID from the run response or GET /agents/{id}/runs):

curl -sS    "$BASE/agents/$AGENT_ID/runs/$RUN_ID"        -H "Authorization: Bearer $KEY"
curl -sS -N "$BASE/agents/$AGENT_ID/runs/$RUN_ID/stream" -H "Authorization: Bearer $KEY"

Multi-agent system:

curl -sS -N -X POST "$BASE/mas/$SYSTEM_ID/conversation/stream" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"message": "A customer is unhappy that their order is late", "input_variables": {}}'

Key reference

Each key acts as its own caller — runs one key starts aren’t visible to another.

Rotate and revoke

Changes apply within about 5 seconds of saving.

• Revoke — delete the key’s entry, or set enabled: false.
• Rotate — add the new key, move your integration to it, then delete the old one.
• Close an agent — set its enabled: false under exposed. Every key loses access at once.

config/api-keys.yaml isn’t part of the signed bundle, so editing it never fails verification. Keep a copy when you upgrade: unpacking a new archive writes a fresh, all-off file.

Troubleshooting