LLM Actions

LLM actions generate text using AI models. Define a prompt template with dynamic placeholders, and Hyphen fills them from the execution context before calling the model.

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": "summarize_document",
    "kind": "llm",
    "description": "Summarize a document in 3 bullet points",
    "template": "Summarize the following document in 3 bullet points:\n\n{{input.document_text}}",
    "model": "gpt-4",
    "max_tokens": 500
  }'

Properties

Property	Type	Required	Description
`action_name`	string	Yes	Unique name for this action
`kind`	`"llm"`	Yes
`template`	string	Yes	Prompt template with `{{ }}` placeholders
`model`	string	Yes	LLM model used for this action
`max_tokens`	number	No	Maximum tokens in the response (default: 256)

Prompt Templates

Use {{ }} syntax for dynamic content in the prompt:

json

{
  "action_name": "extract_invoice_fields",
  "kind": "llm",
  "template": "Extract the following fields from this invoice text and return as JSON:\n- invoice_number\n- vendor_name\n- amount\n- due_date\n\nInvoice text:\n{{input.invoice_text}}",
  "model": "gpt-4",
  "max_tokens": 256
}

Multiple placeholders are supported:

json

{
  "template": "You are a {{input.role}} at {{input.company}}.\n\nAnalyze this customer complaint and draft a response:\n\n{{input.complaint_text}}"
}

Usage in a Workflow

json

{
  "type": "summarize_document",
  "properties": {
    "outputKey": "summary"
  }
}

Start the workflow with input.document_text. The template reads it through {{input.document_text}}, and the step-level properties.outputKey stores the generated text at @summary.

Usage as an Agent Tool

json

{
  "mode": "react",
  "objective": "Read the contract and identify key terms",
  "tools": [{ "type": "action", "name": "summarize_document" }, { "type": "action", "name": "extract_invoice_fields" }]
}

The agent sees the action's description and template parameters in its tool list. It can call summarize_document with { "document_text": "..." }; agent tool input is exposed to the template under input.

Structured Responses

For actions that need JSON or specific fields, state the required format in the template:

json

{
  "action_name": "classify_ticket",
  "kind": "llm",
  "template": "Classify this support ticket. Return ONLY a JSON object with:\n- category: one of [billing, technical, account, other]\n- priority: one of [low, medium, high, critical]\n- summary: one sentence summary\n\nTicket:\n{{input.ticket_text}}",
  "model": "gpt-4",
  "max_tokens": 200
}

The workflow result is still stored as text. If later deterministic steps need individual JSON fields, put a small validation service behind an HTTP action and return a validated object into workflow context.

LLM actions and ReAct agents. LLM actions run one prompt and return the response. Use them for focused work such as summarization, classification, or extraction. Use a ReAct agent when the task needs several decisions or tool calls.

→ Next: [DB Actions](/actions/db)