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

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.

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.

→ Back to Actions overview