Skip to main content
Checks whether a document or business key was already processed by another task, and registers it to the current task if not. Use it to stop the same document from being processed twice, or to make any side effect run once per business key: creating a sales order for a purchase order number, posting an invoice, sending a confirmation email.

​
Enablement and configuration

This native tool is off by default and only runs through a configured tool. Choose:
  • agent scope to share duplicate history across versions of one logical agent
  • workspace scope to share history with other agents that are explicitly given this configured tool
  • what to match by: one document file key, or one or more business key text keys
A configured tool matches by exactly one of the two; a key set that mixes a file key with text keys, or carries more than one file key, is rejected when saved. New configurations start in document mode with one document file key. Business-key mode takes keys such as purchase_order_number and vendor_name, matched together as one identity. Each key may carry a description; when set it becomes the model-facing description of that input, so a builder can say exactly where the value comes from and when to omit it. Scope and key definitions are hidden from the agent and cannot be changed in a tool call. A configuration with no keys is rejected when saved. To catch both a re-sent file and the same item in a different file, configure two tools, one per mode, and call each at the point in the flow where its input exists. They share one registry.

​
Inputs

The configured key names become the tool inputs. In document mode the single input accepts a file ID in the workspace or a file URL attached to the current task; call the tool only when a file is attached, and never pass another value such as a document number in its place. In business-key mode the inputs accept the identifying values exactly as they appear on the document or record. label is optional human-readable context, such as a document title or order reference, that is shown if a later task matches the registration. A document-mode call can run before extraction. A business-key call requires every configured key so a partial identity cannot be registered; omit them all while the values are not yet known.

​
Matching behavior

File matching hashes the exact bytes with SHA-256. Visually identical files with different bytes do not match. Text matching is exact as well: values are hashed as supplied, so case, whitespace, and punctuation all change the identity, and “INV-001” and “inv-001” are two different invoices. Only the order of keys in the editor is irrelevant, because the complete name/value set is sorted by name before hashing. Extraction must therefore return each key in a stable form. An empty value, or an unresolved ${var_N} template placeholder, counts as not supplied rather than being registered. The database stores fingerprints, the supplied text values, file metadata, the original task, and the configured-tool identity. It does not store file bytes or presigned URLs in the duplicate registry. Each call carries one identifier. If its fingerprint belongs to another task, the result is duplicate with a stable detection ID and nothing is registered. Retrying from the original task returns already_registered; retrying a duplicate task reuses its existing detection row. The registry is shared platform infrastructure; this configured tool is one way to write to it, and each registration records which surface created it. Entry points agree only when they fingerprint the same key set: a file-hash check never matches a business-key registration. Deduplication is across tasks, not within one. The first call registers the fingerprints to the current task, so call the tool only once the item is accepted for processing. A later call from the same task with the same values returns already_registered rather than duplicate.

​
Output

  • status: new, already_registered, or duplicate
  • is_duplicate: whether another task owns at least one fingerprint
  • checks: per-signal outcome, the key_values (as supplied) that were matched or registered, original task metadata, and detection ID when matched
  • previous_duplicates: earlier tasks detected against the same original fingerprint
Treat duplicate conservatively: inspect the original task before performing downstream side effects.

​
Expected errors and limits

  • base tool invoked without a configured-tool identity
  • invalid or incomplete configured text keys
  • file ID outside the workspace or URL not attached to the current task
  • agent scope used without a logical-agent identity
  • file storage or duplicate registry unavailable
Version 1 provides exact matching only. It has no semantic or fuzzy matching, backfill, expiry policy, manual override, or review-management UI. Detection review status is reserved for future workflows.