Publishing

What is a Published Agent?

A Published Agent is a tenant-owned route that exposes one Agent Profile over a public HTTPS surface. Publishing does not change the profile itself: it adds a row that maps (tenant, slug) to the profile and tracks the public knobs that the Chat Gateway enforces on every request. Published agents are:

Slug-addressed: the public URL is https://<gateway>/v1/chat/{tenant}/{slug}
Profile-backed: every chat turn runs against the same profile that conductor users invoke privately
API-key authenticated: bearers are HMAC-hashed with a pepper; plaintext is shown exactly once
Soft-deleted: unpublishing keeps the row for history, conditional unique indexes on unpublished_at IS NULL
Tenant-scoped: Postgres row-level security partitions every read and write

Public API Access

Manage published agents through the Conductor API. Send chat messages to the agent’s publicUrl using a key issued for that published agent. See the Chat Gateway API for requests and responses.

Data Model

Six Postgres tables back every public chat turn. All six are RLS-scoped by current_setting('app.tenant_id').

Table	Purpose
`published_agents`	One row per (tenant, slug); maps to a profile, holds public knobs
`agent_api_keys`	One row per minted key, stores HMAC hash and metadata
`conversations`	One row per chat thread; pins a stable conversation id to a runtime session id
`conversation_messages`	Append-only user and assistant turns plus optional stored errors
`gateway_runs`	Run-level audit trail with `dispatching`, `running`, `ok`, or `error` status
`usage_records`	Append-only ingress meter rows for accepted public chat requests

Soft-Delete and Uniqueness

published_agents uses one partial unique index, published_agents_tenant_slug_active, on (tenant_id, slug) WHERE unpublished_at IS NULL. There is no database-level unique constraint on (tenant_id, profile_name): at most one active row per profile is an application-level invariant only, not enforced by the schema. Unpublishing stamps unpublished_at so the slug can be re-used immediately while history stays intact.

LISTEN / NOTIFY

published_agents and agent_api_keys carry triggers that emit published_agents_changed and agent_api_keys_changed notifications. The chat gateway currently reads on every request; the route cache wired through these channels is a planned follow-up.

API Key Identity

The gateway never sees plaintext keys after issuance. The full lifecycle: Tokens follow the format ao_<env>_<base32-22> where <env> is an operator-configured deployment tag (1-16 lowercase alphanumeric characters, read from AGENT_ORC_ENV, defaulting to dev when unset) rather than a fixed set of values. The base32 tail is 22 chars of random entropy. Reaction surface:

Revoke: DELETE /api/profiles/{name}/keys/{id} stamps revoked_at; the gateway returns 401 unauthorized on the next request without leaking the key id
Rotation: issue a new key, hand it to the client, then revoke the old one
Lost pepper: every existing key becomes unverifiable; treat this as a full rotation event

Conversations and Public Runs

A conversation_id is the only continuity handle on the public API. The first request mints one; subsequent requests pass it back to reuse the runtime session.

Why Conversation, Not Session?

The public surface uses conversation_id instead of exposing session_id for three reasons:

Encapsulation: Conversations are the public concept; sessions are a runtime detail that may be recycled
Cross-agent isolation: published_id is stamped on the conversation row at creation, and a stolen conversation_id cannot be reused against a different published agent
One identity surface: Surfacing both ids would let callers desync them; the gateway resolves session reuse via the conversation row, not via wire input

Watcher and Public Run IDs

Every chat turn opens one in-process watcher goroutine inside the gateway. The watcher is the single source of truth for terminal conversation_messages writes: sync and stream handlers subscribe to it via an in-process channel, but never write the terminal row themselves. Public run ids (prun_...) are durable: even if the client disconnects, the watcher finishes the run and persists the terminal message. Callers re-attach with GET .../runs/{publicRunId} for the final answer or GET .../runs/{publicRunId}/stream to subscribe to a still-running watcher.

Ingress Metering

After a public chat request is accepted and dispatched to the conductor, the gateway increments an in-memory counter for that (tenant, published agent). The counter flushes to usage_records once per interval as kind='ingress', with published_id and the number of accepted requests since the previous flush. Ingress rows are append-only increments, not cumulative upserts. Tenant-wide usage sums ingress_requests over the selected window, while per-agent metrics filter by published_id. Phase 1 records ingress for stats only, so these rows have cost_usd = 0.

Crash Recovery Sweep

On boot, the chat gateway runs a one-shot sweep:

SELECT * FROM gateway_runs
WHERE status IN ('dispatching', 'running')
  AND created_at > now() - interval '24 hours';

Rows that already have a conductor internal_run_id get a re-attached watcher so the terminal write happens even after a gateway crash. Rows that never made it past dispatch do not have an internal run to resume; the sweep finalizes them as lost. The sweep is logged and continues; a sweep failure never blocks boot.

Public Knobs

Every published row carries the request-shaping knobs the gateway enforces.

Field	Default	Effect
`slug`	kebab-cased profile name	URL path; immutable after publish
`visibility`	`private`	Informational today; reserved for future allowlists
`authMode`	`api_key`	`api_key` or `jwt` (the latter is reserved)
`allowedOrigins`	`[]`	When non-empty, browsers must send a matching `Origin` header
`rateLimitRpm`	`60`	Per-key sliding-window limit; `0` disables limiting
`syncMaxDurationSeconds`	`60`	Upper bound on the sync chat endpoint; bounded `1..270`
`conversationTtlDays`	`null`	Conversation retention; `null` keeps history forever
`exposeToolEvents`	`false`	When true, stream emits `tool` SSE frames
`enabled`	`true`	Hard kill switch independent of unpublish
`monthlyCostCapUsdCents`	`5000` (US$50)	Hard monthly spend ceiling for this published agent, summed across all its API keys; enforced by the spend-cap gate, independent of any tenant-level cap

The rate-limit key is the API key id, not the tenant: an abusive bearer cannot poison the whole tenant.

Tenant Boundary

A published-agent key is scoped to one tenant and agent. Requests must use the matching tenant and slug in the URL. Revoked keys are rejected.

Failure Modes

Symptom	Likely cause
`401 unauthorized`	Token malformed, revoked, wrong tenant, or pepper rotated
`404 not_found` (auth path)	Slug never published or unpublished
`503 endpoint_paused`	Published agent has `enabled=false`
`403 origin_not_allowed`	Browser sent an `Origin` not on `allowedOrigins`
`429 rate_limited`	Per-key sliding window exhausted; `Retry-After: 60`
`502 upstream`	The agent service could not complete the request; retry or contact support if it persists
`504 sync_timeout`	Run did not finish within `syncMaxDurationSeconds`; resume via `runs/{id}`
`410 lost`	Public run id older than 24 h and watcher never re-attached

See Publishing an Agent for the publishing walkthrough, or the Chat Gateway API and Conductor publish endpoints for wire-level reference.

Get Started

Core Concepts

Guides

Runbooks

What is a Published Agent?

Public API Access

Data Model

Soft-Delete and Uniqueness

LISTEN / NOTIFY

API Key Identity

Conversations and Public Runs

Why Conversation, Not Session?

Watcher and Public Run IDs

Ingress Metering

Crash Recovery Sweep

Public Knobs

Tenant Boundary

Failure Modes

​What is a Published Agent?

​Public API Access

​Data Model

​Soft-Delete and Uniqueness

​LISTEN / NOTIFY

​API Key Identity

​Conversations and Public Runs

​Why Conversation, Not Session?

​Watcher and Public Run IDs

​Ingress Metering

​Crash Recovery Sweep

​Public Knobs

​Tenant Boundary

​Failure Modes

What is a Published Agent?

Public API Access

Data Model

Soft-Delete and Uniqueness

LISTEN / NOTIFY

API Key Identity

Conversations and Public Runs

Why Conversation, Not Session?

Watcher and Public Run IDs

Ingress Metering

Crash Recovery Sweep

Public Knobs

Tenant Boundary

Failure Modes