Agent Configuration

Four resources, four responsibilities

Publishing a version changes no runtime traffic. Provisioning an Agent creates the Environment identity, but selects no version. Activation appends the Agent Release that makes one version current for new Runs.

The Agent Version manifest

The manifest is complete rather than an overlay. It names its schema, instructions, the exact primary model it runs on, the separate model used for Conversation history compaction, enabled Tools, required Environment bindings, and every finite execution budget used by this API revision.

{
  "schemaVersion": "config.cantora.ai/agent-version/v1alpha3",
  "instructions": "Answer support questions using approved sources and cite the evidence used.",
  "model": {
    "provider": "googleVertex",
    "model": "gemini-3.6-flash",
    "settings": { "thinkingLevel": "low" }
  },
  "contextSnapshotModel": {
    "provider": "openai",
    "model": "gpt-5.6-luna",
    "settings": { "reasoningEffort": "low", "reasoningMode": "standard" }
  },
  "tools": [],
  "requiredBindings": [],
  "integrationDependencies": [],
  "budgets": {
    "maxModelSteps": 12,
    "maxToolCalls": 0,
    "totalWallTimeMs": 240000,
    "modelStepTimeMs": 90000,
    "streamStallTimeMs": 15000,
    "maxInputTokens": 250000,
    "maxOutputTokens": 16000,
    "maxReasoningTokens": 32000,
    "maxTotalTokens": 300000,
    "maxToolResultBytes": 1000000,
    "maxEstimatedCostMicros": 5000000
  }
}

• schemaVersion makes the manifest contract explicit.
• model names one of the providers Cantora runs and that provider's own model identifier. Publication refuses any other provider, and the identifier must name an exact model rather than a moving pointer such as latest.
• contextSnapshotModel independently names the exact model used for asynchronous Conversation history compaction. It may use another provider than model. If omitted, Cantora records the reviewed gpt-5.6-luna configuration shown above.
• settings carries the behavior settings that provider defines, in its own vocabulary. Cantora normalizes no effort scale of its own.
• tools declares the Tool keys this version may invoke.
• requiredBindings declares the Environment configuration that activation must satisfy.
• budgets bounds model steps, Tool calls, time, token classes, Tool-result bytes, and estimated cost for a Run. If maxInputTokens is omitted, Cantora records 250,000; an explicit value overrides that default.

Secrets never belong in the manifest. Connections and credentials are separate Environment resources, so Test and Live do not share mutable access even when they select the same Agent Version.

Publication appends a Version

Cantora normalizes and digests the manifest, then creates the next immutable Agent Version for every new publication. A new publication creates a new Version even when its content matches an older one. The publish request records the authenticated Principal and stable request identifier; Git and CI retain repository and automation details.

Give each logical publication a stable requestId. Reissuing the identical request returns its original Version with a reused outcome; a new request ID produces a created outcome. Keep the returned manifestDigest with the source revision that produced it.

Activation and rollback append history

Activate a version with a reason and the current strong Agent Release ETag in If-Match. A newly provisioned Agent starts at generation zero and returns its initial ETag. A stale precondition returns the current release and ETag so the caller can read the new state and decide again.

Rollback is another activation selecting a previously released immutable version. It rewrites no version or release history and affects new work only; accepted Runs remain pinned to the release they started on.

Next steps

Start with the resource model, then inspect the generated reference for publishing an Agent Version and activating an Agent Release.