Custom Table Actions

Custom table actions give an agent a named, pre-configured operation on a Hyphen-managed table. The registration fixes the table and operation. The agent supplies only the row data or selector fields the action needs.

Registration

bash

curl -X POST https://your-hyphen.example.com/actions \
  -H "X-Org-Id: acme-corp" \
  -H "Content-Type: application/json" \
  -d '{
    "action_name": "log_reconciliation",
    "kind": "custom-table",
    "description": "Log a reconciliation result to the audit table",
    "properties": {
      "table": "recon_audit",
      "operation": "write",
      "key_fields": ["invoice_id"]
    }
  }'

This creates a tool that can write to recon_audit. Calls cannot redirect it to another table or change the operation.

Properties

Property	Type	Required	Description
`action_name`	string	Yes	Unique name for this action
`kind`	`"custom-table"`	Yes
`description`	string	No	Human-readable description (shown to agents)
`properties.table`	string	Yes	Table bound to the action
`properties.operation`	string	Yes	`read`, `write`, `update`, or `upsert`
`properties.key_fields`	string[]	For update/upsert	Fields used to select the row
`properties.where`	object	No	`read`: a fixed filter the agent cannot remove. Values may be `@path` references resolved from the run, such as `"@__run_id"`
`properties.limit`	number	No	`read`: most rows returned

Usage as an Agent Tool

json

{
  "mode": "react",
  "objective": "Check if this invoice was previously processed, and log the current result",
  "tools": [{ "type": "action", "name": "log_reconciliation" }]
}

The agent sees the action name, description, and accepted row fields. It does not choose the table or operation.

For a read, the stored where is a floor. The agent can narrow it by passing column values, for example { "manual_match_id": "mm-7" }, but a stored value always wins for its column, and an agent's own where or limit is refused. A stored filter whose @path has no value in the run refuses the read instead of reading without it.

Example agent response:

json

{
  "thought": "I should log this reconciliation result before completing.",
  "action": "log_reconciliation",
  "action_input": {
    "invoice_id": "INV-001",
    "status": "matched",
    "confidence": 0.95
  }
}

Registered vs Primitive

Use the custom-table primitive for table operations in a workflow:

json

{ "type": "custom-table", "properties": { "table": "log", "operation": "write", ... } }

Use a registered custom-table action when an agent needs a named tool that is limited to one table operation.

Writes that must commit together across tables use the primitive's transaction operation; it is not available as a registered action.

→ Back to Actions overview