Matcher Actions

Matcher actions are pre-configured matching rules. Instead of specifying matcher properties in every workflow, register a configuration once and reference it by name.

Registration

bash

curl -X POST http://localhost:3009/actions \
  -H "X-Org-Id: acme-corp" \
  -H "Content-Type: application/json" \
  -d '{
    "action_name": "invoice_payment_matcher",
    "kind": "matcher",
    "description": "Match invoices to payments by invoice number with 2% tolerance and 5-day date window",
    "left": "@input.invoices",
    "right": "@input.payments",
    "matchOn": ["invoice_number", "vendor_id"],
    "tolerance": 0.02,
    "dateWindowDays": 5,
    "fuzzyThreshold": 85,
    "descriptionKey": "description"
  }'

Properties

Property	Type	Required	Description
`action_name`	string	Yes	Unique name for this action
`kind`	`"matcher"`	Yes
`left`	@path	Yes	Left dataset path
`right`	@path	Yes	Right dataset path
`matchOn`	string[]	Yes	Fields for exact matching
`tolerance`	number	No	Numeric tolerance (decimal)
`dateWindowDays`	number	No	Date window (±days)
`fuzzyThreshold`	number	No	Text similarity 0–100
`descriptionKey`	string	No	Field for fuzzy matching

All matching properties work identically to the Matcher primitive. The difference is that a matcher action saves the configuration for reuse.

Registered vs Primitive

Use the matcher primitive when matching configuration varies per workflow:

json

{ "type": "matcher", "properties": { "matchOn": ["invoice_id"], "tolerance": 0.01 } }

Use a registered matcher action when you have a standard matching configuration used across multiple workflows:

json

{ "type": "invoice_payment_matcher", "properties": { } }

Usage in a Workflow

json

{
  "type": "invoice_payment_matcher",
  "properties": {
    "invoices": "@input.new_invoices",
    "payments": "@input.recent_payments"
  }
}

Properties passed at execution time can override the registered defaults.

Usage as an Agent Tool

json

{
  "mode": "react",
  "objective": "Reconcile this batch of transactions",
  "tools": [{ "type": "action", "name": "invoice_payment_matcher" }]
}

The agent can invoke the matcher during its reasoning when it needs to compare datasets.

→ Next: Custom Table Actions