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 model it runs on, enabled Tools, required Environment bindings, and every finite execution budget used by this API revision.

{
  "schemaVersion": "config.cantora.ai/agent-version/v1alpha2",
  "instructions": "Answer support questions using approved sources and cite the evidence used.",
  "model": {
    "provider": "googleVertex",
    "model": "gemini-3.6-flash",
    "settings": { "thinkingLevel": "low" }
  },
  "tools": [],
  "requiredBindings": [],
  "budgets": {
    "maxModelSteps": 12,
    "maxToolCalls": 0,
    "totalWallTimeMs": 240000,
    "modelStepTimeMs": 90000,
    "streamStallTimeMs": 15000,
    "maxInputTokens": 100000,
    "maxOutputTokens": 16000,
    "maxReasoningTokens": 32000,
    "maxTotalTokens": 140000,
    "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.
• 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.

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 is content-addressed

Cantora normalizes and digests the manifest. Publishing identical content reuses the existing Agent Version; changing behavior produces a new immutable version. The publish request also records repository, commit, path, workflow, and run provenance without making source control the runtime authority.

Use the publish response's outcome to distinguish a newly created version from a reused one, and keep the returned manifestDigest with the source revision that produced it.

Activation and rollback append history

Activate a version with a reason, source provenance, 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.