Agents

Partially update an agent

Partially updates an existing agent. Identical to PUT — both perform partial updates.

patch/v1/projects/{project_id}/agents/{agent_id}

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/agents/{agent_id}
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Path parameters

agent_idstring required
Example:agent_V1StGXR8Z5jdHi6B

Agent public ID

Headers

If-Matchstring

The version the caller believes the resource holds, as an entity tag (3 or "3"). Equivalent to expected_version in the request body; * states no precondition beyond the resource existing. A mismatch is 409 VERSION_CONFLICT.

Request body

ai_provider_idstring nullable

Public ID of the AI provider to pin. Mutually exclusive with model_route_id; set to null when switching to a route.

model_route_idstring nullable

Model route in the same project. Mutually exclusive with ai_provider_id and model; set to null to clear.

namestring nullable

Display name; null clears it.

instructionsstring nullable

System instructions, sent as the system message of every generation; null clears them.

modelstring nullable

Model identifier on the pinned AI provider; null falls back to the provider's default model. Cannot be combined with model_route_id.

max_stepsinteger nullable

Maximum agent loop steps per turn; null restores the default of 20.

tool_choiceunknown
active_tool_idsstring[] nullable

Persisted tools from tool_bindings the model sees on every step. null or [] leaves every bound tool active. See Active Tools.

guardrail_idsstring[] nullable

Guardrails attached at the agent scope.

temperaturenumber nullable

Sampling temperature passed to the model; null restores the provider's default.

output_schemaobject 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.

max_context_messagesinteger nullable

Maximum number of recent messages included in the context window. Null means no limit.

max_output_tokensinteger 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.

single_session_per_actorboolean nullable

When true, only one open session per actor_id is allowed for this agent.

trace_content_mode'full' | 'none' | 'null' nullable

Zero-retention opt-in for this agent. null inherits the project's setting; none means trace and generation content is never written. Setting full under a project whose own mode is none is refused with 400.

on_approval_expiry'terminate' | 'react' | 'null' 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_labelstring nullable

Optional tag for the config version this write archives (e.g. pre-tone-change). Annotates the version only — it is not stored on the agent and is not part of the config, so labelling a change is never itself a change. Ignored when the write changes nothing, since no version is created.

expected_versioninteger nullable

The version the caller believes the resource holds. When the resource is at any other version the write is refused with 409 VERSION_CONFLICT and nothing is written; meta.current_version on that response names the version in force.

Omit it to write unconditionally. Omitting it does not make the write unordered: two writes that reach the server together are still serialized, and the one whose version was taken first is refused the same way. What the field adds is refusing a write whose author read the resource some time ago and has not seen what happened since.

The If-Match header carries the same precondition for a client that prefers the HTTP spelling. Sending both with different versions is 400 VALIDATION_FAILED.

Example request

{
  "tool_bindings": [
    {
      "tool_id": "tool_V1StGXR8Z5jdHi6B"
    }
  ],
  "boundary_policy": {
    "statement": [
      {
        "effect": "Allow",
        "action": [
          "memories:*",
          "agents:DeleteAgent"
        ],
        "resource": [
          "srn:proj_abc:memories:*"
        ],
        "condition": {
          "StringEquals": {}
        }
      }
    ]
  },
  "knowledge_config": {
    "tags": {
      "team": "finance",
      "env": "prod"
    }
  },
  "max_output_tokens": 1024,
  "reasoning": {
    "effort": "low"
  },
  "version_label": "pre-tone-change",
  "expected_version": 3
}

Response

Agent updated

idstring

Public ID of the agent

project_idstring

Public ID of the owning project

ai_provider_idstring nullable

Public ID of the pinned AI provider. Null when the agent resolves its model through model_route_id instead.

model_route_idstring 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.

namestring nullable

Display name

instructionsstring nullable

System instructions guiding behavior

modelstring nullable

Model identifier

max_stepsinteger 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_choiceunknown
stop_conditionsobject[] 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_idsstring[] nullable

Subset of the bound tools that are active

guardrail_idsstring[] nullable

Guardrails attached at the agent scope, governing every tool call the agent makes.

step_rulesobject[] 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.

boundary_policyobject nullable

Allowed/denied runtime actions

temperaturenumber nullable

Sampling temperature

output_schemaobject 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.

max_context_messagesinteger nullable

Maximum number of recent messages to include in the context window sent to the model. When null, all messages are included.

max_output_tokensinteger 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.

single_session_per_actorboolean

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' | 'null' 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' | 'null' 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.

versioninteger

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.

created_atstring date-time
updated_atstring date-time

Example response

{
  "id": "agent_V1StGXR8Z5jdHi6B",
  "tool_bindings": [
    {
      "tool_id": "tool_V1StGXR8Z5jdHi6B"
    }
  ],
  "knowledge_config": {
    "tags": {
      "team": "finance",
      "env": "prod"
    }
  },
  "max_output_tokens": 1024,
  "reasoning": {
    "effort": "low"
  },
  "version": 3,
  "active_release": {
    "stable_version": 3,
    "canary_version": 4,
    "canary_percent": 20,
    "promotion_gate": "eval_V1StGXR8Z5jdHi6B"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.