---
title: "Update an agent"
method: PUT
path: "/projects/{project_id}/agents/{agent_id}/"
tags: ["Agents"]
---

# Update an agent

`PUT /projects/{project_id}/agents/{agent_id}/`

## Request

- Base URL: `https://api.parsewise.ai/api/v1`
- URL: `https://api.parsewise.ai/api/v1/projects/{project_id}/agents/{agent_id}/`
- Auth: API key in header `X-API-Key`

Replace the agent's configuration (instructions, dimensions, etc.). If the change invalidates already-extracted results (e.g. editing the prompt), the affected extraction results are cleared automatically. Returns the updated agent.

## Path parameters

- `agent_id` string, uuid, required
- `project_id` string, uuid, required

## Request body

- V1AgentRequest: Configuration for an agent: the natural-language instructions and options that tell the extraction pipeline what to pull out of the project's documents. Used as the request body for `POST /agents/` (creating a new agent) and `PATCH /agents/{agent_id}/` (updating one). On `PATCH`, only the fields you supply are changed; omitted fields are left untouched. `dimensions` is special: omit it to leave the existing dimensions in place, or pass an empty array to remove them all. Successful responses return the full agent representation (including server-managed fields such as `id`, `created_at`, and `extraction_status`); see the response schema for that endpoint for the exact shape.
  - `name` string, required: Human-readable name shown for the agent (e.g. "Contract value").
  - `extraction_instructions` string: Natural-language instructions describing what the agent should extract from each document.
  - `value_type` 'string' | 'number' | 'list': * `string` - string * `number` - number * `list` - list
  - `unit` string: Optional unit for numeric values (e.g. `USD`, `%`, `kg`). Used to normalise extracted values into a consistent unit and for display.
  - `examples` string: Free-form examples of expected values, used to steer the agent towards the right kind of answer.
  - `inconsistency_instructions` string: Custom instructions for inconsistency checking. If empty, default instructions will be used.
  - `resolution_instructions` string: Custom instructions for entity resolution. If empty, default instructions will be used.
  - `enable_complex_calculations_in_resolution` boolean: Enable advanced computational analysis for complex resolution tasks involving calculations or data transformations.
  - `enable_web_search` boolean: Enable web search to supplement extraction results with data from the web.
  - `web_search_instructions` string: Web search task for each cell; required when enable_web_search is true.
  - `value_if_not_found` string: Value shown when no extraction is found. If empty, 'n/a' is used.
  - `dimensions` V1AgentDimensionRequest[]: Dimensions to configure on the agent, in declaration order. Each entry attaches an existing project dimension to the agent and configures its values. Omit to create the agent with no dimensions; on update, omit to leave existing dimensions untouched and pass an empty array to remove them all.
    - `allowed_values` string[], nullable: TAG only. Restricts this agent to these tag values, including ones no document has yet; send null or omit it to follow all tag values.
    - `dimension_id` string, uuid, required: ID of the dimension to attach to the agent. System-managed dimensions (source DOCUMENT or TAG) attach by ID with `values` omitted — their values are maintained automatically. Use `allowed_values` to restrict a TAG dimension to a subset of tag values.
    - `are_values_dynamic` boolean: When false, `values` defines the fixed set of allowed values. When true, leave `values` empty: a list agent discovers the values from the project documents before this agent runs.
    - `values` string[]: Allowed values for this dimension. Required (and must be non-empty) when `are_values_dynamic` is false; ignored when a list agent supplies the values, which then follow its resolved list. Must be omitted or empty for system-managed dimensions.
    - `source_agent_id` string, uuid, nullable: ID of a list agent in the same project (without web search or dimensions) whose results become the allowed values of this dimension; agents using the dimension wait for it to finish. To stop using it, send `are_values_dynamic` false with the values to keep; the list agent itself is kept. Omit to keep the current setting.
    - `description` string: Optional update to the dimension's description. Note: this updates the dimension across every agent in the project that shares it.
    - `value_type` union: Optional update to the dimension's value type. Only `string` (free text) and `number` (numeric, pair with a unit) are supported. Note: this updates the dimension across every agent in the project that shares it. * `string` - String * `number` - Number
      - 'string' | 'number': * `string` - String * `number` - Number
      - unknown
    - `add_to_all_agents` boolean: When true, this dimension is also attached to every other agent in the project (and applied to any future agents created in the project).
  - `agent_type` 'extraction' | 'derived': * `extraction` - extraction * `derived` - derived
  - `derived_prompt` string: LLM prompt for derived agents. May contain @[Name](uuid) references to agents and documents.
  - `is_evaluation` boolean: Marks a derived agent as an evaluation agent: its prompt is treated as an evaluation criterion scored over the referenced agents, its value type is always number, and it is listed on the evaluation page.
  - `derived_agent_references` V1DerivedAgentReferenceRequest[]: Agents whose resolved values this derived agent consumes. On write each entry may identify its agent by `agent_id`, by `agent_name`, or by both — `agent_id` is tried first, and `agent_name` is the portable identifier to use when moving an agent configuration into another project. A reference that matches no agent in the project, or a name shared by several agents, is rejected. Both fields are always returned on read, with the name taken from the referenced agent.
    - `agent_id` string, uuid: Identifier of the referenced agent. Always returned on read. On write, supply this or `agent_name`; when both are given and this one matches an agent in the project, it wins.
    - `agent_name` string: Name of the referenced agent, always returned on read from the referenced agent itself. On write it may be supplied instead of `agent_id` — use it when moving an agent configuration into another project, where the original ids no longer apply. Matched exactly; a name shared by several agents in the project is rejected.

## Response `200`

- TopicInstance
  - `id` string, uuid, required: Stable identifier for the agent (UUID).
  - `project_id` string, uuid, required: Identifier of the project this agent belongs to.
  - `template_id` string, uuid, nullable, required: Identifier of the agent template this agent was created from, or null if the agent was created from scratch.
  - `dimensions` V1AgentDimensionResponse[], required: Dimensions configured on this agent, in display order. Each dimension carries its dimension id, mapping id, name, ordered list of values, and whether values are dynamically discovered from documents (are_values_dynamic=true) or static.
    - `source_agent_id` string, uuid, nullable, required: List agent that discovers the allowed values from the documents, or null when the values are configured manually.
    - `dimension_id` string, uuid, required: Identifier of the dimension (project-scoped dimension definition this instance attaches to the agent).
    - `dimension_mapping_id` string, uuid, required: Identifier of this dimension's attachment to the agent. Carries the agent-specific settings for the dimension, such as `order` and `are_values_dynamic`.
    - `name` string, required: Human-readable dimension name (e.g. "Region", "Year").
    - `description` string, required: Free-text description of the dimension, or empty string if none was provided.
    - `values` string[], required: Dimension values used to key extraction results. When `source_agent_id` is set these follow the list agent's resolved list; otherwise they are the values configured on the agent.
    - `value_count` integer, required: Number of entries in `values`.
    - `order` integer, required: Display/declaration order of this dimension relative to the agent's other dimensions.
    - `are_values_dynamic` boolean, required: True when the values are discovered from the documents by the list agent in `source_agent_id`; false when the values are configured on the agent.
    - `allowed_values` string[], nullable, required: TAG only: the tag values this agent is restricted to, which may include tags no document has yet. Null means the agent follows all tag values.
    - `source` 'CUSTOM' | 'DOCUMENT' | 'TAG', required: * `CUSTOM` - CUSTOM * `DOCUMENT` - DOCUMENT * `TAG` - TAG
  - `created_at` string, date-time, required: Timestamp when the agent was created.
  - `extraction_status` 'Pending' | 'Processed' | 'No Result', required
  - `requires_attention` boolean, required: True if any of this agent's resolved values need attention (for example, unresolved inconsistencies between source documents).
  - `improvement_tip_summary` string, nullable, required: Summary of the selected active improvement suggestion, or null when none is available.
  - `supplying_agent_names` string[], required
  - `name` string: Human-readable name shown for the agent (e.g. "Contract value").
  - `extraction_instructions` string: Natural-language instructions describing what the agent should extract from each document.
  - `value_type` 'string' | 'number' | 'list': * `string` - string * `number` - number * `list` - list
  - `unit` string: Optional unit for numeric values (e.g. `USD`, `%`, `kg`). Used to normalise extracted values into a consistent unit and for display.
  - `examples` string: Free-form examples of expected values, used to steer the agent towards the right kind of answer.
  - `inconsistency_instructions` string: Custom instructions for inconsistency checking. If empty, default instructions will be used.
  - `resolution_instructions` string: Custom instructions for entity resolution. If empty, default instructions will be used.
  - `enable_complex_calculations_in_resolution` boolean: Enable advanced computational analysis for complex resolution tasks involving calculations or data transformations.
  - `web_search_instructions` string: Web search task for each cell; required when enable_web_search is true.
  - `enable_web_search` boolean: Enable web search to supplement extraction results with data from the web.
  - `value_if_not_found` string: Value shown when no extraction is found. If empty, 'n/a' is used.
  - `inconsistency_summary` string, nullable: AI-generated summary of why extracted values disagree across documents. Populated when inconsistencies are detected; null otherwise.
  - `agent_type` 'extraction' | 'derived': * `extraction` - Extraction * `derived` - Derived
  - `derived_prompt` string: LLM prompt for derived agents. May contain @[Name](uuid) references to agents and documents.
  - `is_evaluation` boolean: Marks a derived agent as an evaluation agent: its prompt is treated as an evaluation criterion scored over the referenced agents, its value type is always number, and it is listed on the evaluation page.
  - `derived_agent_references` V1DerivedAgentReference[]: Agents whose resolved values this derived agent consumes. On write each entry may identify its agent by `agent_id`, by `agent_name`, or by both — `agent_id` is tried first, and `agent_name` is the portable identifier to use when moving an agent configuration into another project. A reference that matches no agent in the project, or a name shared by several agents, is rejected. Both fields are always returned on read, with the name taken from the referenced agent.
    - `agent_id` string, uuid: Identifier of the referenced agent. Always returned on read. On write, supply this or `agent_name`; when both are given and this one matches an agent in the project, it wins.
    - `agent_name` string: Name of the referenced agent, always returned on read from the referenced agent itself. On write it may be supplied instead of `agent_id` — use it when moving an agent configuration into another project, where the original ids no longer apply. Matched exactly; a name shared by several agents in the project is rejected.

---

[API](https://skmtc.dev/parsewise/apis/parsewise-api.md) - [All operations](https://skmtc.dev/parsewise/apis/parsewise-api/llms.txt) - [OpenAPI document](https://skmtc.dev/parsewise/apis/parsewise-api/revisions/5db46512debf?raw)