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
| Field | Type | Description |
|---|---|---|
id | string | Public ID of the agent |
project_id | string | Public ID of the owning project |
ai_provider_id | string, nullable | Public ID of the pinned AI provider. Null when the agent resolves its model through model_route_id instead. |
model_route_id | string, nullable | Public 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. |
name | string, nullable | Display name |
instructions | string, nullable | System instructions guiding behavior |
model | string, nullable | Model identifier |
tool_bindings | object[], nullable | Tools attached to this agent, one binding object per tool — the canonical attachment field. See Tool Bindings. |
max_steps | integer, nullable | Maximum 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_choice | any | Tool 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_conditions | object[], nullable | Conditions 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_ids | string[], nullable | Subset of the bound tools that are active |
guardrail_ids | string[], nullable | Guardrails attached at the agent scope, governing every tool call the agent makes. |
step_rules | object[], nullable | Per-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_ids | string[], nullable | Under 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_as | caller | agent | What 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. |
temperature | number, nullable | Sampling temperature |
knowledge_config | object, nullable | Knowledge retrieval config injected before every generation |
output_schema | object, nullable | JSON 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_caching | object, nullable | Prompt 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_messages | integer, nullable | Maximum number of recent messages to include in the context window sent to the model. When null, all messages are included. |
max_output_tokens | integer, nullable | Maximum 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. |
reasoning | object, nullable | How 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_actor | boolean | When 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_mode | full | none, nullable | Agent-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_expiry | terminate | react, nullable | What 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. |
version | integer | Current 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_release | object, nullable | Staged rollout in progress, or null when all traffic serves this config. |
created_at | string (date-time) | |
updated_at | string (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 arequires_actionpause shares one chain — and caps it below the deployment's own ceiling. Hitting the cap ends the chain with stop reasonchain_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_pathsmatches 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 spellsmin_similarity, under the agent record's name for it. It readssimilarity_score, not the fusedscoreresults are ordered by (two scores, one contract). Omitted, there is no floor.rrf_k— thekin the fusion term1 / (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;0disables 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.
- CLI
- SDK
- curl
naturali patch-agent \
--project-id proj_V1StGXR8Z5jdHi6B \
--agent-id agent_V1StGXR8Z5jdHi6B \
--knowledge-config '{ "document_paths": ["/handbook/"], "limit": 5 }'
const { data: agent } = await naturali.agents.patchAgent({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
agent_id: 'agent_V1StGXR8Z5jdHi6B',
},
body: {
knowledge_config: {
document_paths: ['/handbook/'],
limit: 5,
},
},
});
curl -X PATCH https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/agents/agent_V1StGXR8Z5jdHi6B \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"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:
| Mark | Covers | Read back by |
|---|---|---|
| The instructions | tool definitions and instructions | every step and turn, while they are unchanged |
| The step's last message | all of the above, plus the conversation so far | the 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_messageswindow 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_tokensand writes ascache_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.
- CLI
- SDK
- curl
naturali patch-agent \
--project-id proj_V1StGXR8Z5jdHi6B \
--agent-id agent_V1StGXR8Z5jdHi6B \
--prompt-caching '{ "enabled": true }'
const { data: agent } = await naturali.agents.patchAgent({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
agent_id: 'agent_V1StGXR8Z5jdHi6B',
},
body: {
prompt_caching: { enabled: true },
},
});
curl -X PATCH https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/agents/agent_V1StGXR8Z5jdHi6B \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"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_as | A turn runs as | Requires |
|---|---|---|
caller (default) | the caller (the key, or the trigger, that started it) capped by policy_ids; no policy_ids, no cap | the caller's own permissions for what the agent does |
agent | policy_ids alone, inside the agent's project: the agent's own grant | a 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.reactspawns 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 …/versionslists the archive, newest first;GET …/versions/{version}reads one.POST …/versions/{version}/restorecopies an old config onto the agent as a new version rather than rewinding the counter, so history stays append-only.PUT …/releaseserves two archived versions side by side:canary_percentof traffic getscanary_version, the reststable_version. Assignment is deterministic — it hashes the actor behind the request — so one end user never flip-flops between configs mid-conversation.POST …/release/promotemakes the canary live;POST …/release/abortrestores 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.
| Value | Meaning |
|---|---|
null (default) | Inherit the project's mode |
none | Zero-retention: this agent's content is never written |
full | Record 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_rowsnames eachprovider,modelandcomponentwithout a price. Choose a model fromGET /v1/models.400 MODEL_NOT_OFFEREDwhen 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
- CLI
- SDK
- curl
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"}]'
const { data: agent } = await naturali.agents.createAgent({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
body: {
ai_provider_id: 'aip_V1StGXR8Z5jdHi6B',
name: 'support-triage',
instructions: 'Triage inbound support mail. Be brief.',
tool_bindings: [{ tool_id: 'tool_V1StGXR8Z5jdHi6B' }],
},
});
curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/agents \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"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
- CLI
- SDK
- curl
naturali create-agent \
--project-id proj_V1StGXR8Z5jdHi6B \
--model-route-id route_V1StGXR8Z5jdHi6B \
--name resilient-triage
const { data: agent } = await naturali.agents.createAgent({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
body: {
model_route_id: 'route_V1StGXR8Z5jdHi6B',
name: 'resilient-triage',
},
});
curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/agents \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "model_route_id": "route_V1StGXR8Z5jdHi6B", "name": "resilient-triage" }'
Run it and wait for the answer
- CLI
- SDK
- curl
naturali create-agent-generation \
--project-id proj_V1StGXR8Z5jdHi6B \
--agent-id agent_V1StGXR8Z5jdHi6B \
--wait true \
--messages '[{"role":"user","content":"Summarise this ticket in one line."}]'
const { data: generation } = await naturali.agents.createAgentGeneration({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
agent_id: 'agent_V1StGXR8Z5jdHi6B',
},
query: { wait: true },
body: {
messages: [{ role: 'user', content: 'Summarise this ticket in one line.' }],
},
});
curl -X POST \
"https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/agents/agent_V1StGXR8Z5jdHi6B/generate?wait=true" \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "messages": [{ "role": "user", "content": "Summarise this ticket in one line." }] }'
Stage a canary release
- CLI
- SDK
- curl
naturali set-agent-release \
--project-id proj_V1StGXR8Z5jdHi6B \
--agent-id agent_V1StGXR8Z5jdHi6B \
--stable-version 3 \
--canary-version 4 \
--canary-percent 20
await naturali.agentVersions.setAgentRelease({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
agent_id: 'agent_V1StGXR8Z5jdHi6B',
},
body: { stable_version: 3, canary_version: 4, canary_percent: 20 },
});
curl -X PUT \
https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/agents/agent_V1StGXR8Z5jdHi6B/release \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "stable_version": 3, "canary_version": 4, "canary_percent": 20 }'
Make an agent zero-retention
- CLI
- SDK
- curl
naturali patch-agent \
--project-id proj_V1StGXR8Z5jdHi6B \
--agent-id agent_V1StGXR8Z5jdHi6B \
--trace-content-mode none
await naturali.agents.patchAgent({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
agent_id: 'agent_V1StGXR8Z5jdHi6B',
},
body: { trace_content_mode: 'none' },
});
curl -X PATCH https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/agents/agent_V1StGXR8Z5jdHi6B \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "trace_content_mode": "none" }'
Send trace_content_mode: null to go back to inheriting the project's setting.