Build governed agent connections

KRNLA gives agents an authenticated identity, deterministic policy checks, governed LLM calls, and durable inbox delivery. Your agents and their business logic stay in your own applications.

Quickstart

1. Sign up or sign in. During beta, a verified new account may wait for access approval.
2. Create a workspace, register an agent, and reveal its credential once. Save it in the agent runtime’s secret manager, never in source code or a browser.
3. Install the SDK for your server-side language, set KRNLA_API_KEY and KRNLA_GATEWAY_URL=https://gateway.krnla.com, then connect.
4. Configure policies before sending governed content. Traffic without a matching enabled ALLOW or REDACT rule is blocked.

Python

python -m pip install krnla==0.1.0
export KRNLA_GATEWAY_URL=https://gateway.krnla.com
# Set KRNLA_API_KEY using your runtime secret manager.
from krnla import KRNLA
krnla = KRNLA.connect()
print(krnla.identity.agent_id)

TypeScript / JavaScript

npm install @krnla/sdk@0.1.0
import { KRNLA } from '@krnla/sdk';
const krnla = await KRNLA.connect();
console.log(krnla.identity?.agentId);

Identity and workspace access

connect() validates the credential and asks the Gateway for the registered agent identity. It does not make an idle agent “online,” intercept arbitrary traffic, or register actions automatically. The Gateway rechecks credential and agent status on subsequent requests. Workspace owners manage membership and roles in the console; platform signup admission is a separate authority.

Credential rotation and revocation are managed through the console. A revoked credential or disabled agent cannot authenticate new requests. A request already admitted before revocation may finish.

Deterministic governance

Policies run in priority order against bounded, normalized facts and deterministic detectors. The actions are ALLOW, BLOCK, and REDACT. No match means BLOCK. REDACT that cannot safely produce governed content becomes BLOCK. Policy changes publish immutable revisions; the Gateway uses the exact authoritative revision, and missing authority or configuration fails closed.

A disabled policy can be archived to free a current-policy slot. Archiving creates a new revision; old immutable snapshots remain for audit. You can simulate a policy in the console without sending content to a provider or another agent.

Governed LLM calls

Configure a provider and model in the console. The provider credential stays on KRNLA’s server side; agents use only a public provider configuration ID. Current fixed adapters support OpenAI Responses v1 and Google Gemini. The console exposes an explicit live validation state, and operators should validate a provider before enabling real use. KRNLA does not claim universal provider compatibility.

# Python
response = krnla.llm.generate(
    provider_config_id="YOUR_PROVIDER_CONFIG_ID",
    input=[{"role": "user", "text": "Summarize the report."}],
)

// TypeScript
const response = await krnla.llm.generate({
  providerConfigId: 'YOUR_PROVIDER_CONFIG_ID',
  input: [{ role: 'user', text: 'Summarize the report.' }],
});

Governed streaming is available through llm.stream. Some REDACT patterns cannot be safely streamed and fail closed. KRNLA does not retry uncertain provider calls automatically.

Configured agent connections

Create a connection in KRNLA from Agent A to Agent B and select its event/interface. Agents use an opaque connection ID, not B’s URL or credential. An allowed send stores the governed content encrypted in B’s inbox and returns QUEUED. BLOCK never creates a deliverable inbox message; REDACT stores only governed content.

# Python
delivery = krnla.send_connection(
    connection="YOUR_CONNECTION_ID", data={"reportId": "example-1"}
)

// TypeScript
const delivery = await krnla.sendConnection({
  connection: 'YOUR_CONNECTION_ID', data: { reportId: 'example-1' },
});

Direct HTTPS push/webhooks are a future optional transport. They are not the default and require a secure pinned-egress runtime before production use.

Polling, leases, and acknowledgement

Agent B authenticates with its own KRNLA credential and explicitly runs an inbox consumer loop. Polling leases up to 20 messages for 30 seconds. An unacknowledged message can be delivered again, so handlers should deduplicate by delivery ID. Inbox payloads expire after 24 hours. Acknowledgement is a separate event from policy ALLOW or queueing.

# Python
for message in krnla.poll_inbox(limit=10):
    process(message.content)
    krnla.acknowledge(delivery_id=message.delivery_id, lease_id=message.lease_id)

// TypeScript
for (const message of await krnla.pollInbox({ limit: 10 })) {
  await process(message.content);
  await krnla.acknowledge({ deliveryId: message.deliveryId, leaseId: message.leaseId });
}

Activity and interfaces

The console shows bounded activity metadata. Message bodies, credentials, provider secrets, detected content, and pre-redaction values are not activity data. A configured connection is an intended route; a declared interface is an agent assertion; an observed relationship appears only after acknowledged typed delivery. These are distinct states.

Agents may declare a complete desired set of emitted and accepted event names through declare. KRNLA also discovers bounded structural metadata after real acknowledged messages. Declarations and observations never include payload examples.

Limits, errors, and retries

The SDK exposes typed authentication, rate-limit, policy, protocol, and service-unavailable errors. A normal policy BLOCKED outcome is a result. The SDK does not repeat non-idempotent sends or LLM calls automatically. If the outcome is UNKNOWN, use delivery ID or application idempotency to reconcile before a manual retry.

• Current policy set: at most 200 non-archived policies.
• Inbox poll: at most 20 leased messages per request, 30-second lease, 24-hour payload TTL.
• Message data: 1–8 bounded string fields.
• Agent declarations: at most 256 bounded emitted/accepted items.

Security boundary

KRNLA derives organization authority from the credential or browser session, never from a caller-supplied tenant ID. Gateway authorization, policy revision, agent disablement, and credential revocation are checked against authoritative state. Arbitrary destination egress remains pinned and fail-closed. Agent credentials are issued once, hashed at rest, and should be rotated if exposed.

Provider credentials, inbox encryption keys, and browser sessions belong in managed production custody. Production release requires verified backup restoration, key recovery, abuse controls, monitoring, and a final security audit. See security information and support.