Credentials and secrets

Agent templates should contain references to credentials, not secret values.

Model connections

{
  "llm": {
    "provider": "openai",
    "model": "gpt-5.6-luna",
    "connection": { "mode": "agenta", "slug": "openai-production" }
  }
}

mode: "agenta" resolves a project connection; omit slug to use the project default. mode: "self_managed" tells Agenta not to inject a model credential and cannot be combined with a slug.

Connected applications

A gateway_connection tool stores the provider, integration key, and existing project connection slug. OAuth tokens and API keys stay in the project connection and are resolved by the gateway.

Code tools

A code tool's secrets array lists secret names. At execution time the resolver injects available values into the script environment. Missing-secret behavior depends on the service policy and can fail resolution.

MCP headers

Use connection.credentials.type: "header_secret_refs" and map each HTTP header to a project secret slug. Do not put bearer tokens in static headers.

Sandbox credentials

Bind a project secret into the sandbox explicitly:

{
  "secret": { "slug": "package-registry-token" },
  "binding": { "type": "env", "name": "NPM_TOKEN" }
}

The binding name must be a valid environment variable name.

Per-request fields

Invoke requests also accept secrets and credentials. These are sensitive runtime inputs, not a place to persist credentials in client logs or source control. Prefer project-managed references for reusable agents.