Configuration for the upsert_entity tool. This tool creates or updates entities in a target project. The decision between creating a new entity vs updating an existing one is driven by the **reference input** specified via `reference_source_property_id`. If that reference input resolves to an existing entity, the tool updates it; otherwise (empty match or no reference), it creates a new entity (when `allow_insert` is true). ## How to configure Every `upsert_entity` property needs at minimum: - `target_project_id` — the project to write entities into - `allow_insert` — whether creation of new entities is allowed Then, depending on the use case, you link source inputs via the config fields below. Each `*_property_id` field refers to a **source property** that must also be wired as an input on the property definition (via `inputs`). ### Quick reference — config fields and their linked inputs ``` ┌─────────────────────────────────────────┬──────────────────────────────┐ │ Config field │ Expected input type │ ├─────────────────────────────────────────┼──────────────────────────────┤ │ reference_source_property_id │ :reference (update selector) │ │ json_input_property_id │ :json (free-form params) │ │ parent_entity_id_source_property_id │ :reference (parent entity) │ │ property_mappings[].source_property_id │ any typed (text, number, …) │ └─────────────────────────────────────────┴──────────────────────────────┘ ``` ## Scenario 1 — Create-only (no reference) Use case: always create a new entity in the target project. No reference input is needed — `reference_source_property_id` is null (or omitted) and there are no reference inputs wired. Every execution creates a fresh entity. ``` Source Project ┌──────────────────────────────────────────────────┐ │ Properties: │ │ [source_name] type: text │ │ [source_email] type: text │ │ [upsert_prop] tool: upsert_entity │ │ inputs: [source_name, source_email] │ │ tool_config.upsert_entity_config: │ │ target_project_id: │ │ allow_insert: true │ │ reference_source_property_id: null │ │ property_mappings: │ │ - target: │ │ source: │ │ - target: │ │ source: │ └──────────────────────────────────────────────────┘ │ ▼ always creates Target Project ┌──────────────────────────────────────────────────┐ │ Properties: │ │ [target_name] type: text │ │ [target_email] type: text │ └──────────────────────────────────────────────────┘ ``` Inputs on the upsert_entity property: ```json [ {"property_id": ""}, {"property_id": ""} ] ``` ## Scenario 2 — Update-only (no insert) Use case: sync field values into an existing entity matched by a reference. ``` Source Project (where the upsert_entity property lives) ┌──────────────────────────────────────────────────┐ │ Properties: │ │ [ref_to_target] type: reference ──────────┐ │ │ [source_name] type: text │ │ │ [source_email] type: text │ │ │ [upsert_prop] tool: upsert_entity │ │ │ inputs: [ref_to_target, │ │ │ source_name, source_email] │ │ │ tool_config.upsert_entity_config: │ │ │ target_project_id: │ │ │ allow_insert: false │ │ │ reference_source_property_id: │ │ │ ◄── decides │ │ │ update/create │ │ property_mappings: │ │ │ - target: │ │ │ source: │ │ │ - target: │ │ │ source: │ │ └──────────────────────────────────────┼────────┘ │ │ │ Target Project ◄──────────────────────┘ │ ┌──────────────────────────────────────────────────┐ │ Properties: │ │ [target_name] type: text │ │ [target_email] type: text │ └──────────────────────────────────────────────────┘ ``` Inputs on the upsert_entity property: ```json [ {"property_id": ""}, {"property_id": ""}, {"property_id": ""} ] ``` ## Scenario 3 — Upsert (update if matched, create if not) Same as Scenario 2 but with `allow_insert: true`. When `reference_source_property_id` resolves to no entity, a new entity is created in the target project with the mapped field values. ## Scenario 4 — Create into a collection sub-project Use case: create child entities under a parent entity in a collection. ``` Parent Project ┌──────────────────────────────────────────────────┐ │ Properties: │ │ [ref_to_parent] type: reference ───┐ │ │ [items_json] type: json │ │ │ [upsert_prop] tool: upsert_entity│ │ │ inputs: [ref_to_parent, │ │ │ items_json] │ │ │ tool_config.upsert_entity_config: │ │ target_project_id: │ │ allow_insert: true │ │ reference_source_property_id: null │ │ (no update, always create) │ │ json_input_property_id: │ │ │ │ parent_entity_id_source_property_id: │ │ ◄── parent entity │ │ batch_entity_upsert: true │ └──────────────────────────────────────────────────┘ │ │ ▼ ▼ Parent Project (self-ref) Child Sub-Project ┌─────────────────┐ ┌─────────────────┐ │ entity matched │ │ new entity │ │ by ref_to_parent│ │ created here │ │ becomes parent │ │ with parent_id │ └─────────────────┘ └─────────────────┘ ``` ## Scenario 5 — Upsert into a collection sub-project Combines update-or-create with collection parenting: ``` tool_config.upsert_entity_config: target_project_id: allow_insert: true reference_source_property_id: parent_entity_id_source_property_id: batch_entity_upsert: true property_mappings: - target: , source: ``` Here three reference inputs are needed: - `ref_to_child` → decides update vs create in the child project - `ref_to_parent` → supplies `parent_entity_id` for new child entities ## Auto-discovery (fallback) When `reference_source_property_id` is null (not set), the tool falls back to auto-discovering the update reference by picking the first `:reference` input that is not already consumed by `property_mappings`, `json_input_property_id`, or `parent_entity_id_source_property_id`. **For API integrations, explicit configuration via `reference_source_property_id` is strongly recommended** to avoid ambiguity when multiple reference inputs exist.

200AgentBuilder.StartResponse

400Common.APIError

401Common.APIError

403Common.APIError

404Common.APIError

409Common.APIError

422Common.APIError

500Common.APIError