Create an agent

Create a new agent on the project. Returns the full created agent (same shape as GET /agents/{agent_id}/). Use POST /agents/launch/ afterwards to run the extraction pipeline.

On this page

HTTP request 

POST https://api.parsewise.ai/api/v1/projects/{project_id}/agents/

URI Parameters

Name In Required Type Description
project_id path Yes string (uuid)  

Request Header

Name Required Type Description
X-API-Key Yes string API key with the pw_live_ prefix. See Authentication.

Request Body

Supported content types: application/json, application/x-www-form-urlencoded, multipart/form-data.

Name Required Type Description
name Yes string Human-readable name shown for the agent (e.g. “Contract value”).
extraction_instructions No string Natural-language instructions describing what the agent should extract from each document.
value_type No ValueTypeF41Enum Type of value the agent produces.
unit No string Optional unit for numeric values (e.g. USD, %, kg). Used to normalise extracted values into a consistent unit and for display.
examples No string Free-form examples of expected values, used to steer the agent towards the right kind of answer.
inconsistency_instructions No string Custom instructions for inconsistency checking. If empty, default instructions will be used.
resolution_instructions No string Custom instructions for entity resolution. If empty, default instructions will be used.
enable_complex_calculations_in_resolution No boolean Enable advanced computational analysis for complex resolution tasks involving calculations or data transformations.
enable_web_search No boolean Enable web search to supplement extraction results with data from the web.
value_if_not_found No string Value shown when no extraction is found. If empty, ‘n/a’ is used.
dimensions No array<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.
agent_type No V1AgentAgentTypeEnum What kind of agent to create. Derived agents run an LLM prompt over other agents’ resolved values instead of extracting from documents; in per-document projects a derived agent runs once per document, with that document’s content and its referenced values available to each run. Defaults to extraction on create; omitting the field on update preserves the existing type.
derived_prompt No string LLM prompt for derived agents. May contain @Name references to agents and documents.
is_evaluation No 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 No array<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.

Responses

Status Type Description
201 TopicInstance —

Security

  • ApiKeyAuth — apiKey — in X-API-Key header. API key with pw_live_ prefix.

Python example 

import os
import requests

API_KEY = os.environ["PARSEWISE_API_KEY"]
BASE_URL = "https://api.parsewise.ai/api/v1"

project_id = "<uuid>"

body = {
    "name": "...",
    "extraction_instructions": "...",  # optional
    "value_type": "string",  # optional
    "unit": "...",  # optional
    "examples": "...",  # optional
    "inconsistency_instructions": "...",  # optional
    "resolution_instructions": "...",  # optional
    "enable_complex_calculations_in_resolution": False,  # optional
    "enable_web_search": False,  # optional
    "value_if_not_found": "...",  # optional
    "dimensions": [],  # optional
    "agent_type": "extraction",  # optional
    "derived_prompt": "...",  # optional
    "is_evaluation": False,  # optional
    "derived_agent_references": [],  # optional
}

resp = requests.post(
    f"{BASE_URL}/projects/{project_id}/agents/",
    headers={"X-API-Key": API_KEY},
    json=body,
)
resp.raise_for_status()
print(resp.json() if resp.content else None)

Definitions

ExtractionStatusEnum

Type: string. One of:

  • Pending
  • Processed
  • No Result

NullEnum

Type: any. One of:

  • None

Source33eEnum

Type: string. One of:

  • CUSTOM
  • DOCUMENT
  • TAG

TopicInstance

Name Required Type Description
id Yes string (uuid) Stable identifier for the agent (UUID).
project_id Yes string (uuid) Identifier of the project this agent belongs to.
template_id Yes string (uuid) (nullable) Identifier of the agent template this agent was created from, or null if the agent was created from scratch.
dimensions Yes array<V1AgentDimensionResponse> 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.
created_at Yes string (date-time) Timestamp when the agent was created.
extraction_status Yes ExtractionStatusEnum Whether the agent has finished extracting against the project’s current documents. Pending while extractions are missing or in flight, Processed once all expected resolutions are present, and No Result when the agent has completed but produced no resolved values.
requires_attention Yes boolean True if any of this agent’s resolved values need attention (for example, unresolved inconsistencies between source documents).
improvement_tip_summary Yes string (nullable) Summary of the selected active improvement suggestion, or null when none is available.
name No string Human-readable name shown for the agent (e.g. “Contract value”).
extraction_instructions No string Natural-language instructions describing what the agent should extract from each document.
value_type No ValueTypeF41Enum Type of value the agent produces.
unit No string Optional unit for numeric values (e.g. USD, %, kg). Used to normalise extracted values into a consistent unit and for display.
examples No string Free-form examples of expected values, used to steer the agent towards the right kind of answer.
inconsistency_instructions No string Custom instructions for inconsistency checking. If empty, default instructions will be used.
resolution_instructions No string Custom instructions for entity resolution. If empty, default instructions will be used.
enable_complex_calculations_in_resolution No boolean Enable advanced computational analysis for complex resolution tasks involving calculations or data transformations.
enable_web_search No boolean Enable web search to supplement extraction results with data from the web.
value_if_not_found No string Value shown when no extraction is found. If empty, ‘n/a’ is used.
inconsistency_summary No string (nullable) AI-generated summary of why extracted values disagree across documents. Populated when inconsistencies are detected; null otherwise.
agent_type No TopicInstanceAgentTypeEnum What kind of agent this is. Extraction agents extract values from documents; derived agents run an LLM prompt over other agents’ resolved values.
derived_prompt No string LLM prompt for derived agents. May contain @Name references to agents and documents.
is_evaluation No 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 No array<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.

TopicInstanceAgentTypeEnum

Type: string. One of:

  • extraction
  • derived

V1AgentAgentTypeEnum

Type: string. One of:

  • extraction
  • derived

V1AgentDimensionRequest

One dimension to attach to an agent, used inside the dimensions array of an agent create/update request.

A dimension breaks an agent’s extraction down by a categorical axis (for example, by document type or by a tag). Reference the dimension you want to attach by its dimension_id and supply the allowed values (or set are_values_dynamic to discover them from the documents at extraction time). On update the array is authoritative: a previously attached dimension omitted from it — including system-managed ones — is detached from the agent. To remove all dimensions from an agent, send dimensions: [].

Name Required Type Description
dimension_id Yes string (uuid) 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.
are_values_dynamic No boolean When true, allowed values for this dimension are discovered dynamically from the project’s documents during extraction. When false, values defines the fixed set of allowed values.
values No array<string> Allowed values for this dimension. Required (and must be non-empty) when are_values_dynamic is false; ignored when values are dynamic. Must be omitted or empty for system-managed dimensions.
description No string Optional update to the dimension’s description. Note: this updates the dimension across every agent in the project that shares it.
value_type No ValueTypeF41Enum | NullEnum 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.
add_to_all_agents No 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).

V1AgentDimensionResponse

One dimension attached to an agent, as returned in the dimensions list of an agent response.

A dimension breaks an agent’s extraction down by a categorical axis (for example, by document type or by a tag). Each entry here pairs the dimension definition (dimension_id) with how it is configured on this specific agent (allowed values, whether values are discovered dynamically from the documents, etc.).

Name Required Type Description
dimension_id Yes string (uuid) Identifier of the dimension (project-scoped dimension definition this instance attaches to the agent).
dimension_mapping_id Yes string (uuid) 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 Yes string Human-readable dimension name (e.g. “Region”, “Year”).
description Yes string Free-text description of the dimension, or empty string if none was provided.
values Yes array<string> Dimension values used to key extraction results. When are_values_dynamic is true these are discovered from the source documents; otherwise they are the static values configured on the agent.
value_count Yes integer Number of entries in values.
order Yes integer Display/declaration order of this dimension relative to the agent’s other dimensions.
are_values_dynamic Yes boolean True when the dimension’s values are dynamically discovered from documents; false when the values are statically configured.
source Yes Source33eEnum Where the dimension values come from. CUSTOM dimensions are user-defined; DOCUMENT and TAG dimensions are system-managed — their values mirror document file names or document tag values and are maintained automatically.

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 Required Type Description
name Yes string Human-readable name shown for the agent (e.g. “Contract value”).
extraction_instructions No string Natural-language instructions describing what the agent should extract from each document.
value_type No ValueTypeF41Enum Type of value the agent produces.
unit No string Optional unit for numeric values (e.g. USD, %, kg). Used to normalise extracted values into a consistent unit and for display.
examples No string Free-form examples of expected values, used to steer the agent towards the right kind of answer.
inconsistency_instructions No string Custom instructions for inconsistency checking. If empty, default instructions will be used.
resolution_instructions No string Custom instructions for entity resolution. If empty, default instructions will be used.
enable_complex_calculations_in_resolution No boolean Enable advanced computational analysis for complex resolution tasks involving calculations or data transformations.
enable_web_search No boolean Enable web search to supplement extraction results with data from the web.
value_if_not_found No string Value shown when no extraction is found. If empty, ‘n/a’ is used.
dimensions No array<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.
agent_type No V1AgentAgentTypeEnum What kind of agent to create. Derived agents run an LLM prompt over other agents’ resolved values instead of extracting from documents; in per-document projects a derived agent runs once per document, with that document’s content and its referenced values available to each run. Defaults to extraction on create; omitting the field on update preserves the existing type.
derived_prompt No string LLM prompt for derived agents. May contain @Name references to agents and documents.
is_evaluation No 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 No array<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.

V1DerivedAgentReference

Name Required Type Description
agent_id No 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 No 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.

V1DerivedAgentReferenceRequest

Name Required Type Description
agent_id No 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 No 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.

ValueTypeF41Enum

Type: string. One of:

  • string
  • number