Skip to main content

Agents

Create, configure, version and run agents.

Overview​

An agent is a project-scoped configuration — a model source, instructions, sampling and step limits, and a set of tools — that can be run directly or bound to a longer-lived session. Its model comes from either an AI provider pinned with ai_provider_id, or a model route named with model_route_id, which resolves a model with failover. The two are mutually exclusive.

Every write that changes the configuration archives a version, and a release can serve two versions side by side — so an agent is a configuration with history, not just a row you overwrite.

This module is a verbatim mirror of the runtime: every field, method, status code and error shape is the runtime's own, re-rooted under the project in the path.

See the OpenAPI spec for the full endpoint and schema reference, or browse it rendered under API Reference → Agents.

Data Model​

Agent​

FieldTypeDescription
idstringPublic ID of the agent
project_idstringPublic ID of the owning project
ai_provider_idstring, nullablePublic ID of the pinned AI provider. Null when the agent resolves its model through model_route_id instead.
model_route_idstring, nullablePublic ID of the model route that resolves this agent's completion model. Null when the agent pins a provider through ai_provider_id. Mutually exclusive with ai_provider_id and model.
namestring, nullableDisplay name
instructionsstring, nullableSystem instructions guiding behavior
modelstring, nullableModel identifier
tool_bindingsobject[], nullableTools attached to this agent, one binding object per tool — the canonical attachment field. See Tool Bindings.
max_stepsinteger, nullableMaximum agent loop steps before stopping. The budget bounds a turn: a generation that pauses at requires_action and resumes after submit-tool-outputs continues the same turn and spends what is left of it, so a turn that arrives with nothing left completes with stop_reason: "max_steps" instead of calling the model again.
tool_choiceanyTool choice strategy. Accepts a string ("auto", "required") or an object ({ "type": "tool", "tool_name": "my_tool" }). A forcing value ("required" or the object form) forbids a final assistant message on every step of every turn, including a resumed or continued one, so it requires a has_tool_call entry in stop_conditions — otherwise the write is refused with FORCED_TOOL_CHOICE_CANNOT_STOP. A named tool must be one the agent offers under that resolved name, or the write (or, for names only a tool server lists, the generation) is refused with AGENT_TOOL_NOT_OFFERED.
stop_conditionsobject[], nullableConditions that end the agent's work early, on top of max_steps — turn-scoped (has_tool_call) or chain-scoped (max_chain_generations). See the create request body for the accepted shapes.
active_tool_idsstring[], nullableSubset of the bound tools that are active
guardrail_idsstring[], nullableGuardrails attached at the agent scope, governing every tool call the agent makes.
step_rulesobject[], nullablePer-step overrides of tool_choice and active_tool_ids. Steps are numbered from the first step of the turn, and that numbering spans a requires_action pause — a rule fires once per turn, not once per resumption.
policy_idsstring[], nullableUnder run_as: caller, the policies capping the caller's permissions on every generation; null is no cap. Under run_as: agent, the agent's own grant.
run_ascaller | agentWhat policy_ids are. caller: a turn runs as the caller's permissions intersected with policy_ids. agent: a turn runs as policy_ids alone, and the caller needs only agents:CreateAgentGeneration on the agent. See Execution Identity.
temperaturenumber, nullableSampling temperature
knowledge_configobject, nullableKnowledge retrieval config injected before every generation
output_schemaobject, nullableJSON Schema describing the structured object the model must return. When set, non-streaming generations constrain output to this schema and the parsed value is returned as output.object. The schema is enforced on the way back, not just sent to the model: an object that violates it fails the generation with 502 OUTPUT_SCHEMA_VALIDATION_FAILED, naming the violated field. Constraints beyond required/type (minLength, enum, pattern, minItems) are honored and are what reject a structurally valid but degenerate answer. See the Structured Output section in the Agents module docs.
prompt_cachingobject, nullablePrompt caching for this agent's turns. {"enabled": true} marks two cache breakpoints: the end of the system block, which covers the tool definitions and the instructions, and the last message of each step, which covers the conversation so far. A provider that caches by explicit breakpoint then reads, on every later step and every later turn of the session, the whole prefix the previous one sent, and writes only what was appended. Null or omitted is off: a cache write costs more than an uncached token, so an agent whose prefix is never re-read would pay for the privilege. A prefix below the model's minimum cacheable length is not cached. Cache reads are reported as cached_tokens and cache writes as cache_write_tokens on usage; a write with no cache_write_tokens price bills at the input rate.
max_context_messagesinteger, nullableMaximum number of recent messages to include in the context window sent to the model. When null, all messages are included.
max_output_tokensinteger, nullableMaximum number of tokens the model may generate per step of a turn. A response that reaches it stops with stop_reason length. Null leaves the model's default.
reasoningobject, nullableHow much the model reasons before answering. Translated per provider (Anthropic thinking, Gemini thinking config, OpenAI reasoning effort) against what the model supports; a model that cannot reason ignores it. none turns reasoning off where the model allows it. Reasoning tokens are metered as output. Null leaves the model's default.
single_session_per_actorbooleanWhen true, only one open session per actor_id is allowed for this agent. Creating a second open session for the same actor returns 409.
trace_content_modefull | none, nullableAgent-scope zero-retention setting. null (the default) inherits the project's trace_content_mode; none means this agent's trace and generation content is never persisted. An agent may tighten a storing project to none but cannot loosen a none project back to full.
on_approval_expiryterminate | react, nullableWhat happens when one of this agent's held tool calls expires un-approved. null (the default) and terminate end the chain there — the expired approval, its approvals.expired event and the auto-filed approval_expired exception are the whole record. react spawns a continuation that reports the staleness to the agent, for an agent that acts on it.
versionintegerCurrent config version. Starts at 1 and increments on every write that changes the config; each increment archives the new config as an AgentVersion. A write that changes nothing leaves it untouched.
active_releaseobject, nullableStaged rollout in progress, or null when all traffic serves this config.
created_atstring (date-time)
updated_atstring (date-time)

A null model falls back to the provider's default_model. A session or channel window takes precedence over max_context_messages. policy_ids names the project's policies, set as in Limit what an agent may do.

Every resource this table references is servable here: guardrail_ids names guardrails, and everything knowledge_config names — documents and memory stores alike — is covered under Giving an agent knowledge.

Key Concepts​

A model source, not a model​

An agent needs exactly one of ai_provider_id (pin one provider, optionally with model) or model_route_id (resolve through an ordered route with failover). Neither is marked required in the schema, because "exactly one of" is not something OpenAPI can express — but an agent with neither cannot generate. Your first agent generation pins a provider and leaves model null.

Tool bindings​

A binding cannot name a builtin tool: that type is refused with 400 here, on the tool and on an inline binding alike.

tool_bindings is the attachment field: one binding object per tool, each either a reference to a registered tool or an inline definition.

{
"tool_bindings": [
{ "tool_id": "tool_V1StGXR8Z5jdHi6B" },
{ "tool": { "name": "lookup", "type": "http", "execute": { "url": "https://…" } } }
]
}

A reference points at a tool in the same project. An inline definition is resolved fresh at generation time and never persisted as a tool resource — handy for a one-off, and invisible to every other agent. The set is replaced wholesale on every write, so [] detaches everything. Gate a tool with guardrails binds a registered tool by reference.

A binding that does not resolve is dropped​

An mcp binding whose server cannot be reached, or whose credential it refuses, contributes no tool and the turn runs without it. The generation completes carrying no error; the agent is told which tools are unavailable, so it can say it could not reach one rather than claim it lacks the capability. The record is an activity entry of kind tool_resolution_failed — see when a tool does not resolve.

Per-step tool choice​

tool_choice governs every step of the tool loop: "required" forces a tool call on each one, including after the model already has what it needs. step_rules overrides it per step — [{ "step": 1, "tool_choice": "required" }] forces a call on the first step only and leaves the agent's own strategy in effect afterwards. Step numbers span a requires_action pause: a rule fires once per turn, not once per resumption.

A tool_name here, and in a has_tool_call stop condition, is the name the model sees: a builtin tool's action is {name}_{action} (cases_create-playbook-case), an mcp tool's action its own name.

A name the agent does not offer — in tool_choice, a step_rules[].tool_choice or a has_tool_call stop condition — is refused with 400 AGENT_TOOL_NOT_OFFERED, listing the names it does offer in meta.offered_tool_names. The write that leaves such a config is refused. An mcp binding's names come from its server's listing, so an agent with one, and an agent stored with such a name, is refused at generation start instead, before the model is called; a binding unreachable for the turn skips the check.

Stopping early: turns and chains​

stop_conditions ends an agent's work before max_steps is reached, at one of two scopes:

  • { "type": "has_tool_call", "tool_name": "…" } is turn-scoped: the turn ends right after the named tool is called.
  • { "type": "max_chain_generations", "max_generations": <n> } is chain-scoped: it counts generations across an entire continuation chain — a turn resumed after a requires_action pause shares one chain — and caps it below the deployment's own ceiling. Hitting the cap ends the chain with stop reason chain_limit, filed as a matching exception.

A tool_choice that forces a call — "required", or a named-tool object — requires a has_tool_call stop condition naming a tool the choice can actually produce. Without one, the write is refused with 422 FORCED_TOOL_CHOICE_CANNOT_STOP: a forced choice with nothing to end the loop would otherwise force a tool call forever. Debug a failed run pairs the two so a tool failure reproduces on every run.

Structured output​

Set output_schema to a JSON Schema and a non-streaming generation is constrained to it; the parsed value comes back as output.object. The schema is enforced on the way back, not merely sent to the model: a violating object fails the generation with 502 OUTPUT_SCHEMA_VALIDATION_FAILED, naming the field. Constraints beyond type/required — minLength, enum, pattern, minItems — are honored, which is what rejects a structurally valid but degenerate answer.

Structured output is agent configuration, not a per-call argument: two shapes means two agents. It is also mutually exclusive with streaming. The Structured output tutorial attaches a schema and reads output.object back.

Giving an agent knowledge​

knowledge_config is retrieval, resolved before every generation and injected into the model's context. Its document half is the knowledge search request minus the query — the agent's own input is the query:

  • document_ids / document_paths — the subset of the corpus to search. document_paths matches on prefix, so /handbook/ reaches everything filed under it, as in Answer from your documents. Omit both and the whole project's documents are in scope.
  • min_score — the raw cosine floor a vector candidate must reach to be ranked, 0–1: the filter search spells min_similarity, under the agent record's name for it. It reads similarity_score, not the fused score results are ordered by (two scores, one contract). Omitted, there is no floor.
  • rrf_k — the k in the fusion term 1 / (k + rank). Smaller weights the top of each ranking more heavily. Omitted, the deployment default applies.
  • recency_half_life_days — half-life of the decay applied to memory results after fusion; 0 disables it. Omitted, the deployment default applies.
  • limit — how many chunks to inject. Every one of them costs context on every generation, so this is a budget, not a maximum to max out.

A floor above what the corpus scores fails silently: nothing is retrieved, the generation succeeds anyway, and the agent answers without the knowledge it is configured to have. Set it from the similarity_score values a POST /v1/projects/{project_id}/knowledge/search on the same query returns — on a corpus topping out at 0.32, 0.5 retrieves nothing. Answer from your documents reads those values before it sets knowledge_config.

Retrieval is checked as the turn's identity, so the agent's own policy_ids gate it: a Deny on knowledge:SearchKnowledge for a document's resource excludes that document from injection, beside the project's agent_policy_ids cap. Either one is enough to exclude it.

The memory half is the same shape plus a write side: memory_store_ids and tags pick which memory stores to search, and write_memory_store_id names the one the agent may write into — which is what makes the write_memory tool available to it during a generation. That is a capability the agent spends at its own discretion; mining completed turns for facts is the store's decision instead, through a memory rule. See Writing to a store from an agent; Limit what an agent may do sets write_memory_store_id. Give an agent long-term memory pairs memory_store_ids with a rule that fills the store.

naturali patch-agent \
--project-id proj_V1StGXR8Z5jdHi6B \
--agent-id agent_V1StGXR8Z5jdHi6B \
--knowledge-config '{ "document_paths": ["/handbook/"], "limit": 5 }'

Changing knowledge_config is a config change, so it cuts a new agent version like any other.

Prompt caching​

Every step of a turn re-sends everything the step before it sent: the tool definitions, the instructions, then the conversation so far — history, knowledge excerpts and every tool result. Over a multi-step turn that re-sent prefix is most of the bill.

prompt_caching: { "enabled": true } marks two cache breakpoints on every request, and a provider that caches by explicit breakpoint serves what each covers from cache instead of charging for it again:

MarkCoversRead back by
The instructionstool definitions and instructionsevery step and turn, while they are unchanged
The step's last messageall of the above, plus the conversation so farthe next step, and the next turn of the session within the cache TTL

Each step reads the previous step's prefix at the cache-read rate and writes only what it appended.

  • Off by default. A cache write costs more than an uncached token, so an agent whose prefix is never re-read pays for the privilege. It pays off on multi-step, tool-heavy turns, not on short one-step answers.
  • An entry lives five minutes. A turn re-reads the session's previous prefix only if it arrives within five minutes of the last; a channel contact who answers slower pays the write every turn and never the read. Under a max_context_messages window the history shifts every turn, so only the instructions mark is read back.
  • Below the model's minimum, nothing is cached. Claude Haiku 4.5 caches a prefix only from 4,096 tokens; short instructions miss it, and the message mark reaches it once the conversation and tool results grow.
  • Who honors it. Claude models, directly or through Bedrock. Providers that cache automatically, or not at all, ignore the marks.
  • What it costs. Usage reports reads as cached_tokens and writes as cache_write_tokens. On a naturali provider both are priced: Claude reads at 0.1× and writes at 1.25× the input rate, Nova writes free. A component a provider's price book does not carry bills at the input rate.

A turn that pauses for an approval and resumes marks its own last message again; editing the agent mid-turn does not re-cut the instructions mark.

naturali patch-agent \
--project-id proj_V1StGXR8Z5jdHi6B \
--agent-id agent_V1StGXR8Z5jdHi6B \
--prompt-caching '{ "enabled": true }'

Enabling it is a config change, so it cuts a new agent version like any other.

Execution identity​

run_as says what the agent's policy_ids are:

run_asA turn runs asRequires
caller (default)the caller (the key, or the trigger, that started it) capped by policy_ids; no policy_ids, no capthe caller's own permissions for what the agent does
agentpolicy_ids alone, inside the agent's project: the agent's own granta non-empty policy_ids, else 400 AGENT_RUN_AS_REQUIRES_POLICIES

Every tool call of a turn is checked as that identity: an http, mcp, builtin, naturali or pipeline call (each pipeline step included) needs tools:CallTool on the tool, and a builtin or naturali action needs its operation as well. Under caller, the caller and policy_ids must both allow it; under agent, policy_ids alone. A refused call reaches the model as a tool result, { error: { code: "FORBIDDEN", message, meta } } with meta.action naming the action, and the turn goes on. So a key narrowed by capabilities that runs a run_as: caller agent with tools needs tools:CallTool, and so do the agent's policy_ids.

Under agent, the caller needs only agents:CreateAgentGeneration on the agent: its tool calls run under the agent's grant, and so does work they start (a task, a run, a generation). What the caller names in the call itself (a document or tool_output message, a per-call knowledge_config) is still checked as the caller. The generation's acted_as is { principal_type: "agent", principal_id: <agent_id> }. Attaching a policy needs a caller holding every grant it carries, else 403 POLICY_GRANT_NOT_HELD, so the agent's grant is never wider than whoever wrote it.

Running an agent​

POST /v1/projects/{project_id}/agents/{agent_id}/generate takes messages, resolves the agent's tools and runs the model loop. It is background by default: 202 Accepted with a generation_id to poll via GET /v1/projects/{project_id}/generations/{generation_id}. Pass ?wait=true to block and receive the result inline. Your first agent generation polls one to completion.

When the run hits a client-type tool it pauses with requires_action; submit the results to POST /v1/projects/{project_id}/agents/{agent_id}/generate/{generation_id}/tool-outputs to resume it.

stream: true answers Server-Sent Events; a completed stream ends with data: [DONE]. Interleaved with the unnamed delta chunks, event: progress frames say when each step and tool call starts and ends (step null); the result or error frame stays the last data frame. A stream lasts at most 5 minutes: it then ends with an end event naming the generation, which keeps running and is read through GET /v1/projects/{project_id}/generations/{generation_id}:

event: end
data: {"reason":"max_lifetime","generation_id":"gen_...","trace_id":"trace_..."}

A failure after the stream opened arrives as a terminal error frame carrying the error the generation records, and the stream ends without [DONE]:

data: {"error":{"code":"AI_PROVIDER_ERROR","message":"...","meta":{"generation_id":"gen_...","trace_id":"trace_..."}}}

On a naturali-managed provider the frame is concealed like any other provider error.

An agent running another through a builtin tool's create-agent-generation waits up to 5 minutes. A nested generation still running then answers the calling agent with status: running, its generation_id and trace_id, and the calling turn continues; once both have settled, the nested outcome is sent to the calling agent as a continuation in its continuation chain.

Approval expiry​

A tool call held for approval can expire before anyone answers it. on_approval_expiry decides what happens next:

  • terminate (default) ends the chain — the generation stops with an exception recorded, and nothing resumes on its own.
  • react spawns a continuation generation that tells the agent its call expired unanswered, so it can retry, pick another tool, or give up gracefully instead of leaving the caller with a dead chain.

Versioning and staged rollout​

version starts at 1 and increments on every write that changes the config; each increment archives the new configuration as a version. A write that changes nothing leaves it alone.

  • GET …/versions lists the archive, newest first; GET …/versions/{version} reads one.
  • POST …/versions/{version}/restore copies an old config onto the agent as a new version rather than rewinding the counter, so history stays append-only.
  • PUT …/release serves two archived versions side by side: canary_percent of traffic gets canary_version, the rest stable_version. Assignment is deterministic — it hashes the actor behind the request — so one end user never flip-flops between configs mid-conversation.
  • POST …/release/promote makes the canary live; POST …/release/abort restores the stable config. Promote pins by version, so an edit that landed mid-rollout stays an unreleased draft rather than being promoted in its place.

Each generation records the agent_version that served it, which is what makes a rollout measurable. Roll out an agent version splits traffic between two versions, reads agent_version off each run and promotes the canary.

Eval-gated promotion​

A release set with promotion_gate names an eval; promote answers 409 PROMOTION_GATE_UNMET until the newest completed run of that eval on this agent, pinned to the canary version, reads verdict: supported; a newer run that reads otherwise closes the gate again, and the refusal's meta names that run's eval_run_id, claim, verdict and verdict_reasons. The promoted version records that run's eval_run_id. Gate a rollout on an eval hits the 409, then reads the eval_run_id off the promoted version.

Zero-retention agents​

trace_content_mode controls whether this agent's content — prompts, tool arguments, tool results, error payloads — is recorded at all.

ValueMeaning
null (default)Inherit the project's mode
noneZero-retention: this agent's content is never written
fullRecord content, even when other agents in the project do not

An agent may tighten a storing project to none, but cannot loosen a none project back to full — otherwise a project-wide mandate could be escaped by creating a new agent. Tightening stops future writes; content already recorded is purged explicitly through DELETE /v1/projects/{project_id}/generations/{generation_id}/content. Run a zero-retention agent shows the skeleton such a run leaves.

A managed model must carry a price​

Every managed provider carries require_priced_model: true, so POST /v1/projects/{project_id}/agents/{agent_id}/generate generates nothing when the model it would run has no price on that provider:

  • 409 MODEL_NOT_PRICED, before the model is called; nothing is sent, spent or metered. meta.unpriced_rows names each provider, model and component without a price. Choose a model from GET /v1/models.
  • 400 MODEL_NOT_OFFERED when the name is not one the provider serves at all, such as a vendor id.

A generation on your own credential is billed to you by your vendor, so a missing naturali price never refuses it.

The model checked is the one the generation would actually use. An agent on a model route is checked on every target, since failover decides at run time which one serves. While a release is active, each generation runs, and is checked on, the version the release assigns it. The negative balance rule below applies once any target, or any version a release names, is managed.

The same rule holds where a model is written. Creating or updating an agent, a model route target or any other resource that stores a model beside a managed provider answers 400 MODEL_NOT_OFFERED when that model has no price, or is not a catalog model at all — so nothing that starts later, from a trigger, a run or a task, can reach an unpriced one. An update that moves a resource onto a managed provider without naming a model is checked against the model it already stores. meta names the model. Your own credential is never checked.

Beside a managed provider, model is the catalog name everywhere: the agent read, its generations, traces, usage and a builtin get-agent result all answer it.

The refusal exists because an unpriced generation costs nothing to run: it contributes nothing to your usage and nothing to your balance. Serving it would be free in a way neither side could see or account for afterwards, and the cost is frozen once the generation completes.

A plan's run allowance can stop generation​

On Free, the same routes answer 403 PLAN_LIMIT_REACHED with resource: "runs", and generate nothing, once the account has used the runs its plan includes for the month. meta carries the limit and the runs used against it, so the message reads "2,000 runs a month, and this account has run 2,043 this cycle". Not in the generated spec.

Unlike the two refusals below, this one is not about managed models. A run is a run whoever's credential served it, so a generation on your own provider credential counts and is refused the same way. What the plan sells is runs.

On Pro and Business nothing is refused. Runs past the allowance are billed at the overage rate, which is what those plans are sold with. Enterprise is not counted at all.

The allowance is the account's, not the project's, and it is the project owner's account — every project the owner pays for draws on the same figure.

The count is taken every few minutes rather than on your request, so it lags slightly: a burst can carry you a little past the allowance before it stops, and the figure the message quotes is as of the last count. It clears when the billing month turns, or immediately if you upgrade.

What was already running is stopped too, the same way a debt stops it: scheduled triggers disabled, eval runs cancelled, orchestration runs and dispatching tasks paused. Reading, cancelling and pausing are never refused.

A negative balance stops managed generation​

The same three routes answer 402 INSUFFICIENT_CREDIT, and generate nothing, when the project owes for usage already served. Also not in the generated spec, and also managed providers only — generation on your own credential is billed to you by your vendor, so your naturali balance is irrelevant to it.

The price, run-allowance and balance refusals hold however a generation starts: a call to this API or an agent's tool call.

A zero balance still generates when the owner has a saved card. The generation that takes the balance below zero is absorbed rather than refused: nothing estimates a call's cost before making it, so nothing can stop the crossing. That last generation is settled on your next top-up, netted automatically — the balance is a sum over a ledger, so a debt and a top-up are just two lines in it. With no saved card, a zero balance is refused too: 402 INSUFFICIENT_CREDIT with meta.card_required: true. Add a card or top up to generate.

What stops is the generation after the balance went negative. Top up and it resumes; the debt is subtracted from the top-up.

The balance is the project owner's, not the caller's. A member generating on a project spends the owner's balance, which is what makes the owner the payer.

Everything that starts generation carries this refusal, not only the three routes above: an eval run, an orchestration run and a paused one handed back by POST /v1/projects/{project_id}/orchestration-runs/{orchestration_run_id}/resume or POST /v1/projects/{project_id}/orchestration-runs/{orchestration_run_id}/human-input, a fired trigger, a task moved into a state or resumed, and the outputs handed back to a generation that stopped on a client tool (POST /v1/projects/{project_id}/agents/{agent_id}/generate/{generation_id}/tool-outputs).

Those pick their models one at a time as they run, so each generation in them is checked for a price as it starts, and a start is measured against the owner's balance whichever provider each generation ends up on.

What no refusal reaches is a scheduled firing, a step inside a run already under way, or a task's automation chain — none of them passes through this API at all. Those are stopped instead, by the reconciliation that finds the debt: the schedule is disabled, the eval run cancelled, and the orchestration run and the task's automation paused so a top-up can resume them where they stopped.

Updating and deleting​

PUT and PATCH are both partial updates on this resource — the runtime treats them identically, so PUT does not blank the fields you omit. DELETE answers 409 while dependent generations or traces exist; force=true deletes them along with the agent. Deploy a system from a template force-deletes a used agent this way.

Examples​

Create an agent on a pinned provider​

naturali create-agent \
--project-id proj_V1StGXR8Z5jdHi6B \
--ai-provider-id aip_V1StGXR8Z5jdHi6B \
--name support-triage \
--instructions "Triage inbound support mail. Be brief." \
--tool-bindings '[{"tool_id":"tool_V1StGXR8Z5jdHi6B"}]'

Create an agent that generates through a route​

naturali create-agent \
--project-id proj_V1StGXR8Z5jdHi6B \
--model-route-id route_V1StGXR8Z5jdHi6B \
--name resilient-triage

Run it and wait for the answer​

naturali create-agent-generation \
--project-id proj_V1StGXR8Z5jdHi6B \
--agent-id agent_V1StGXR8Z5jdHi6B \
--wait true \
--messages '[{"role":"user","content":"Summarise this ticket in one line."}]'

Stage a canary release​

naturali set-agent-release \
--project-id proj_V1StGXR8Z5jdHi6B \
--agent-id agent_V1StGXR8Z5jdHi6B \
--stable-version 3 \
--canary-version 4 \
--canary-percent 20

Make an agent zero-retention​

naturali patch-agent \
--project-id proj_V1StGXR8Z5jdHi6B \
--agent-id agent_V1StGXR8Z5jdHi6B \
--trace-content-mode none

Send trace_content_mode: null to go back to inheriting the project's setting.