Skip to main content

Build agents with Cortega

Develop your agent against a Cortega gateway endpoint and a configured model name. Your application owns its prompts, memory, tool loop, and user experience; Cortega supplies model access, configured governance, and usage visibility. You can then call Cortega APIs to show cost per task, read agent verdicts, or request verification explicitly.

Cortega is not itself a foundation model. A concrete or virtual model name in your request resolves to upstream models. A configured team router can change that selection. This lets you keep model selection and governance in Cortega while developing the application against a stable endpoint. Compatibility still depends on the selected provider: test tool calling, structured output, context limits, and streaming with every target model.

Why build this way?​

Application needWhat Cortega providesWhat the application still owns
Try or switch modelsConcrete models, virtual models, and configured team routingQuality evaluations and provider feature compatibility
Keep provider credentials out of appsA Cortega identity key instead of upstream provider keysSecure storage of that identity key
Apply organization rulesConfigured budgets, model authorization, and request/response guardrailsTask logic, safe tool execution, and handling rejected calls
Govern remote toolsMCP server and tool authorization through the gatewayRouting every relevant tool call through that gateway
Understand cost per taskApplication instance analytics, including attributed governance costA stable run id and an appropriate cost refresh strategy
Verify a legal draftExplicit AI Verifier invocation or a configured inline legal guardrailHuman review and decisions about unverified results

These benefits require operator configuration. Registering an application groups traffic; it does not attach guardrails or grant tool permissions. Calls made directly to a provider or tool server bypass Cortega.

1. Configure your development boundary​

  1. Configure a provider and model in Cortega, authorize the application's team, and create an LLM identity key (ck_…). Copy the gateway LLM URL from Client Setup, including /v1.
  2. Choose a model name the key can access. GET /v1/models lists available concrete and virtual names. For a stable application-facing name, configure a virtual model; review team routing because it can override the requested selection.
  3. Attach the intended guardrails and budgets to the relevant identity or team. Test a normal request and a request that should be rejected through the actual gateway.
  4. Register an Application with an ID header such as X-Agent-Run-Id. Use one value for all LLM and MCP calls in a task, and a new value for the next task.
  5. If the app needs reporting, create a separate API Access key (crt_…) with analytics:read, restricted to the appropriate applications. Add agents:run only if it needs explicit verifier calls.

Keep keys on the application server. A browser should call your backend, which authenticates the user and chooses the appropriate Cortega identity. Use separate identities for workers with different privileges.

2. Make a model call​

The gateway accepts OpenAI-compatible chat completion requests. Existing compatible model clients can use the gateway base URL and identity key; a separate Cortega model SDK is not required.

export CORTEGA_LLM_BASE_URL="https://YOUR_GATEWAY/v1"
export CORTEGA_LLM_KEY="YOUR_LLM_IDENTITY_KEY"
export CORTEGA_MODEL="YOUR_CONFIGURED_MODEL"
export CORTEGA_APP="my-agent"
export CORTEGA_RUN_ID="run-001"

curl --fail-with-body "$CORTEGA_LLM_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $CORTEGA_LLM_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Cortega-Application: $CORTEGA_APP" \
  -H "X-Agent-Run-Id: $CORTEGA_RUN_ID" \
  -d "{\"model\":\"$CORTEGA_MODEL\",\"messages\":[{\"role\":\"user\",\"content\":\"Explain how you would review a contract.\"}]}"

Use the same headers on every turn. X-Cortega-Application labels the workload; the registered ID header groups the run. Neither replaces authentication. For sensitive requests, the gateway also accepts X-Cortega-Sensitivity; confidential and restricted require a suitable Sensitive authorization on the team's classifier, otherwise the request is refused.

The request above is a minimal starting point. In your application, configure the same base URL, identity key, and attribution headers in a compatible model client, then use the analytics request below to read usage for the run.

3. Add a tool loop and governed MCP​

When the model returns tool calls, validate arguments, execute authorized tools, append tool results, and ask the model for the next turn. Bound the number of turns and support cancellation. A tool call requested by a model is not permission to execute it.

For remote MCP tools, register the server in Cortega and grant the caller's team the required tools. Use the gateway's MCP endpoint and an MCP identity. Initialize the MCP session, discover available tools, and call them using the MCP protocol; preserve the session id and send your run header on each request. Use a compatible MCP client rather than treating /mcp as a plain REST tool endpoint.

LLM tool-call review and MCP authorization address different steps: the first examines what the model proposes, while the second governs access when a gateway tool call executes. Local filesystem or application tools need their own execution controls.

4. Read cost and invoke verification​

The console/API host is separate from the gateway LLM URL. Set CORTEGA_API_BASE to the management API prefix, including /api/v1, and use a crt_… API Access key:

curl --fail-with-body \
  -H "Authorization: Bearer $CORTEGA_API_KEY" \
  "$CORTEGA_API_BASE/analytics/apps/my-agent/instances/run-001"

Use the registered application slug and URL-encode dynamic path segments. Analytics arrives asynchronously: an immediate missing instance is pending data, not proof of zero cost. traffic.cost_usd includes LLM and attributed governance charges; the component breakdown separates them. Some telemetry counts and token fields are JSON strings. Session-agent verdicts can remain accumulating until the conversation is quiet and only appear for enabled, licensed agents configured for that application.

For an explicit legal verification request, a key needs agents:run:

curl --fail-with-body "$CORTEGA_API_BASE/agents/run" \
  -H "Authorization: Bearer $CORTEGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent":"legal","request_text":"Review this legal draft.","response_text":"PASTE THE DRAFT TO VERIFY"}'

This runs the verifier without the inline correction loop or persisted findings. CourtListener must be configured on the installation. Treat unverified as unresolved and show the rationale and citation results to the reviewer. API keys and supported request shapes are defined in the customer-facing OpenAPI contracts.

Applications built with Cortega​

These applications illustrate how model access, tool governance, analytics, and verification fit into an agent product. Each example highlights a pattern you can use in your own agent.

Cortega Arena: compare baseline and governed behavior​

Cortega Arena compares the same agent task with baseline and guarded identities. Support scenarios cover refund policy, financial fraud, and social engineering. Enterprise scenarios explore writing policy, legal hallucinations, and agent poisoning.

For an agent developer, the useful pattern is to keep the task consistent while changing the governance configuration. Evaluate both whether unsafe behavior is stopped and whether ordinary requests still succeed. Rules attached in Cortega can protect the agent without requiring each application to implement its own policy engine.

The legal hallucination scenario also illustrates explicit AI Verifier invocation: an application can request a check and show the findings alongside the generated answer. Inline protection and an application-requested check serve different workflow needs.

vCon Arena: combine model calls with governed tools​

vCon Arena demonstrates customer-service and investigation agents that use both models and MCP tools. Its scenarios explore fraud, sensitive information, and access to conversation records. An investigation can use the same model with different tool identities to demonstrate how access permissions affect what the agent can retrieve.

The reusable pattern is to give related model and tool calls a shared conversation id, govern remote tool access through Cortega, and preserve a conversation record containing transcripts, call activity, guardrail events, and usage. Your application can join its own records to Cortega analytics using that id.

Airia: research a company and explain a score​

Airia researches a company's public AI posture and produces an explainable baseline score. It illustrates an application-owned research and scoring workflow using configurable model access and per-task cost reporting.

For research agents, keep the research logic and scoring criteria in the application, use Cortega for governed model access and usage reporting, and distinguish source evidence from model conclusions. Airia's posture score is an application output, rather than a Cortega governance verdict.

The legal and finance workspace is the largest example and is under construction. Its workflow combines reusable review skills, document analysis, proposed findings, user acceptance or rejection, and tracked changes in Word documents. Per-run usage reporting connects model cost with the document-review task.

The pattern is: submit a document → receive proposed findings → accept or reject findings → apply accepted edits as tracked changes. Keep model proposals separate from document mutations, and preserve human review as the step that authorizes edits.

Cortega's role in this architecture is governed model access, configured protection for sensitive work, verification where required, and task-level cost visibility. The workspace remains a work in progress, with Cortega integration still pending.

SDK and developer-kit direction​

Start with existing provider-compatible clients for model requests and an MCP client for tools. Reimplementing those protocols in a Cortega SDK would add maintenance without improving model compatibility.

For a dedicated Cortega SDK, the best next step is generated TypeScript and Python clients for the Analytics API (including agent invocation) and Edge API, each generated from its customer-facing OpenAPI specification. Keep model/MCP protocols separate. Before publishing packages, add contract checks, scoped-key examples, pagination, timeout/cancellation support, structured HTTP errors, and read retry handling that respects Retry-After. Do not automatically retry model calls or tool mutations: duplicates can incur cost or repeat side effects.

A useful developer kit should also include a bounded tool-loop example, an MCP session example, and a baseline-versus-guarded evaluation harness. The examples on this page establish credentials and run attribution first; the four applications illustrate how those capabilities support complete workflows. Generated clients and that broader kit are recommendations, not currently shipped SDKs.