Custom Table Actions

Custom table actions register pre-configured table operations. Like the Custom Table primitive, they read and write to Hyphen-managed tables — but as registered actions, they can be reused by name across workflows and called by agents as tools.

Registration

bash

curl -X POST http://localhost:3009/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"
  }'

Custom table actions are lightweight registrations — the specific table, operation, and fields are typically provided at the workflow step level or by the agent at runtime.

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)

Usage in a Workflow

When used as a workflow step, provide the table operation details in properties:

json

{
  "type": "log_reconciliation",
  "properties": {
    "table": "recon_audit",
    "operation": "write",
    "keys": ["run_id", "timestamp"],
    "values": ["@__run_id", "@now"],
    "fields": {
      "matched_count": "@matched.length",
      "exception_count": "@exceptions.length",
      "status": "completed"
    }
  }
}

The operation types and field references work identically to the Custom Table primitive: read, write, update, and upsert.

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" }]
}

When used as an agent tool, the agent provides the table, operation, and fields in its action_input. The agent sees the action's description to understand what the tool does.

Example agent response:

json

{
  "thought": "I should log this reconciliation result before completing.",
  "action": "log_reconciliation",
  "action_input": {
    "table": "recon_audit",
    "operation": "write",
    "keys": ["invoice_id"],
    "values": ["INV-001"],
    "fields": {
      "status": "matched",
      "confidence": 0.95
    }
  }
}

Registered vs Primitive

Use the custom-table primitive for simple, one-off table operations within a specific workflow:

json

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

Use a registered custom-table action when you want agents to be able to use table operations as tools, or when the same table operation pattern is reused across multiple workflows.

→ Back to Actions overview