Skip to main content
Creates or atomically patches one durable structured record of a configured record type.

​
Authentication and enablement

This native tool is off by default. Add it as a configured tool on an agent and select:
  • a workspace Data Store record type
  • agent scope for records shared across that logical agent’s task runs and versions, or workspace scope for records shared with other explicitly configured agents
  • whether the write result may return fields marked sensitive
Record type and scope are configuration-only values. The agent cannot redirect a call to another record type, logical agent, or workspace. A configured record-type contract specializes the record fields shown to the agent. The contract is resolved live for each decision, so record-type edits apply to existing configured tools without re-saving them.

​
Inputs

  • record: top-level fields to create or patch for a contract-backed record type; the configured tool exposes the contract’s typed fields. Contract fields declared as an open object are presented to function-calling models as JSON-encoded strings and decoded before validation; object fields with declared nested properties remain structured objects.
  • record_json: a non-empty JSON object encoded as a string; required instead of record for a contract-free record type so function-calling models can reliably provide arbitrary fields
  • key: required only for a contract-free record type; contract-backed record types derive the key from their configured identity fields
  • expected_version (optional): apply the write only while the stored record is still at this version, taken from an earlier read or write result. Use for read-modify-write updates that must not overwrite a concurrent change. 0 means the record must not exist yet (create-only). A conditional write with a version ≥ 1 never creates a new record: with no stored record to match, it is refused.
Identity fields must be present on every contract-backed write. Fields present in the patch are type-checked. Missing readiness-required fields are accepted.

​
Output

Returns the key, merged JSON value, monotonic version, changed field names, ready, and missing_required_fields. Sensitive values are replaced with [REDACTED] unless sensitive-read access is enabled. Preserve the returned key for later exact get or readiness calls, particularly when a contract uses multiple identity fields or a non-string identity. A refused expected_version write is reported as an outcome, not an error: write_applied: false, precondition_failed: true, and current_record holding the record that stands. The refusal is final — the condition not holding means keeping the stored record is the correct result — and the agent is instructed to continue without asking the user, retrying only when its own instructions explicitly require overwriting the newer value.

​
Limits and side effects

  • maximum patch size: 256 KiB
  • maximum accumulated record size: 256 KiB
  • maximum top-level fields per patch: 100
  • omitted fields remain unchanged with the default merge write mode — the agent is instructed to send only the fields it is changing, never an empty value for a field it does not intend to overwrite; a record type configured with the replace write mode stores the supplied document as the whole record, removing omitted fields — omission is how a field is deleted. The agent is instructed to send exactly the fields the record should contain afterwards, and to read-and-copy kept fields only when the request changes some fields but clearly intends to keep the rest (never from conversation memory, which may be stale)
  • explicit null is stored as JSON null by default; a record type configured with clear_nulls removes the field instead (identity and readiness-required fields are refused)
  • object and array fields replace their complete previous value; patches do not deep-merge nested data
  • disjoint concurrent patches merge atomically
  • concurrent writes to the same field are last-write-wins unless the write passes expected_version, which refuses the write when the stored version no longer matches
  • records persist until their record type or workspace is deleted, or an operator deletes the record from the Data Store record browser; there is no agent-facing deletion or retention timer
The tool writes one PostgreSQL record and does not launch tasks or emit readiness triggers.

​
Expected errors

  • record type not found
  • base tool enabled without first creating a configured instance
  • missing or invalid identity field
  • undeclared field or configured type mismatch
  • merged record exceeds the accumulated size limit
  • explicit key missing for a contract-free record type
  • configured scope is invalid or agent execution identity is unavailable
  • database operation failed