Agentic applications guide

Register an agentic application so Cortega groups its governed traffic by an id your app already owns, and read per-instance usage and Cortega Agents verdicts through the API.

What it is

An Application ties a name to one ID header: a request header your app puts on every LLM and MCP call it makes through Cortega, for example X-VCon-UUID. Cortega captures whatever value arrives in that header and uses it as a grouping key. Every call that carries the same header value is treated as one unit of work.

Cortega does not generate the value. Your application owns it (a session id, a conversation id, an agent-run id) and sets the same header on the LLM call and every MCP tool call that belongs together.

Registering an application

Open AI Border Gateway → Applications. This needs the View / Register Agentic Applications permission.

1. Add the application:
   • Name: a label, for example vContest Voice.
   • ID header: the exact header your app sends, for example X-VCon-UUID. Matched case-insensitively. Letters, digits, and hyphens only.
   • Applies to: whether the header rides LLM calls, MCP calls, or both.
2. The application is enabled by default. Disable it to stop capturing without deleting the registration.

Rules:

• One application per ID header, per tenant.
• Changes reach the gateways on the next configuration push, about a minute. No gateway restart.
• Traffic that flowed before an application was registered is not retroactively grouped.

Sending the header from your app

Set the header on the request to the AI Border Gateway for both the LLM call (/v1/chat/completions, /v1/messages) and every MCP tool call (/mcp) that belongs to the same unit of work, with the same value.

X-VCon-UUID: 0191ae8b-7412-7000-8800-aad4f5bf0bd5

Where it shows up

Each captured header value becomes a tracked instance of that application. Cortega records, per instance, when it was first and last seen and how many LLM and MCP calls it made. The same value is the key the API reads on.

Reading the API

An external application reads its own usage, and the Cortega Agents verdicts, through the Cortega API. The full reference is on the Analytics API page. Load it into Postman, Insomnia, or a codegen tool.

1. Create a key under System → API Access. Give it the analytics:read scope and, optionally, restrict it to specific applications. Copy the key (crt_...); it is shown once.
2. Call the API with Authorization: Bearer crt_..., base path /api/v1/analytics, on the same host as the console. Responses carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. A 429 includes Retry-After.

The operations:

Operation	Query params	Returns
GET /analytics/apps		Applications this key can see.
GET /analytics/apps/{slug}	from, to	Traffic aggregated across every instance in the window.
GET /analytics/apps/{slug}/instances	from, to, limit, cursor	Distinct ID-header values seen, newest last-seen first. Page with next_cursor.
GET /analytics/apps/{slug}/instances/{instanceId}		One ID value's full LLM and MCP breakdown. Windowed to the instance's own span.
GET /analytics/apps/{slug}/instances/{instanceId}/agents	agent	Each session agent's latest verdict for that ID value: score, label, severity, summary, detail.

from and to are RFC3339. The default window is 24 hours and the span is capped at 90 days. Count and token fields that come straight from the telemetry store are JSON strings; derived totals are numbers.

The cost of one voice session:

curl -H "Authorization: Bearer $CORTEGA_API_KEY" \
  "$CORTEGA_API_BASE/api/v1/analytics/apps/vcontest/instances/0191ae8b-7412-7000-8800-aad4f5bf0bd5"

The Risk agent's verdict on that same session:

curl -H "Authorization: Bearer $CORTEGA_API_KEY" \
  "$CORTEGA_API_BASE/api/v1/analytics/apps/vcontest/instances/0191ae8b-7412-7000-8800-aad4f5bf0bd5/agents?agent=risk"

A session agent returns a score only once the conversation has been quiet long enough to be finalised. Before that the row comes back with status: "accumulating". Only agents your tenant has enabled and licensed, and whose configuration names this application, appear.

Removing an application

Deleting an application stops the grouping and the header stops resolving to it. Historical instance records are kept.