Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.benchgen.com/llms.txt

Use this file to discover all available pages before exploring further.

​
What Is an Action?

An Action is a single, well‑bounded operation your agent can perform while a Topic is active. Where a Topic answers “Should I engage and how do I behave?”, an Action answers “Do this concrete thing now.” Fetch data, update a record, start a workflow, call an external API—each of those should be its own Action. Keep Actions small, deterministic, and composable. If two user requests would require different side effects or different inputs/outputs, you likely need two separate Actions.

​
Parts of an Action

An Action includes a name, when to use (description), inputs, and outputs & mapping.

​
Name

Short verb + object (GetOrderStatus, DraftEmailReply, CreateTicket). Must be distinct from other Actions. Do:
  • Use varied leading verbs (Get, List, Find, Create, Update, Draft, Summarize).
  • Reflect the real outcome (“Get Product Details” not “Call API”).
  • Keep it singular and atomic—one job only.
Avoid:
  • Generic buckets (ProcessRequest, HandleData, ExecuteAction).
  • Stuffing multiple jobs (LookupOrCreateOrUpdateUser).
  • Including transport details (…ViaGraphQL, …FromServiceX) unless versioning/transport is the actual user‑visible contract.
Examples
Less EffectiveMore Effective
ProcessCustomerDataUpdatePhoneNumber
ManageOrdersGetOrderStatus
EmailHandlerDraftEmailReply
Fast test: If two unrelated user requests still “fit” the name, it’s too broad.

​
When to Use (Description)

One crisp sentence (two max) saying outcome + required key input + a disambiguator. Pattern: Return name, price, availability for a product using product_id; exclude archived products. Weak vs Strong:
  • Weak: “Updates a phone number.”
  • Strong: “Update the phone number on an existing contact; create a new contact only if email has no match.”
Tips:
  • Mention 1–2 common trigger phrases only if routing collisions persist.
  • Cut boilerplate (“This action allows the system to…”).
Examples: Less vs More Effective Descriptions
ActionLess EffectiveMore Effective
ChangeProfilePhoneChanges a phone number.Replace the phone on an existing user profile identified by user_id; if the profile doesn’t exist but email is provided, create the profile before updating the phone.
SyncCalendarEventSyncs calendar event.Create or update a calendar event using external_event_id and calendar_id; skip invites for archived calendars and return the normalized event payload.
FindInventoryItemsSearches inventory.Locate in‑stock SKUs by keyword and warehouse_id; exclude discontinued items and limit results to the caller’s organization.
Optional: Trigger Utterances Include 1–3 short examples of user messages that should select this Action:
  • “Show my meetings next Tuesday.”
  • “Do we have medium blue jackets in stock?”
  • “Send the welcome message to the new teammate.”
  • “Pull the latest status for order AB-1042.”

​
Inputs

Explicit list of parameters the Action expects. Guidelines:
  • Mark required vs optional; fail fast if a required one is missing.
  • Specify type and format (ISO 8601 date, lowercase id, 2‑letter country code).
  • Keep names simple (product_id, locale, max_results).
  • Avoid giant free‑form blobs unless absolutely necessary.
  • Validate early; don’t silently coerce types.
Common patterns:
  • Identity: user_id, account_id (scopes requests to the right tenant).
  • Pagination: page, page_size or cursor, limit (set sane caps).
  • Filtering: from_date, to_date, status (document allowed values).
Input Parameter Instruction Examples
ParameterInstructions
resource_idThe unique identifier of the target entity. Accept res_******** format; reject if missing or malformed.
entity_kindThe canonical type of the target (e.g., user, order, product). Infer from context if omitted; prefer explicit input when available.
localeBCP‑47 language tag used for formatting (e.g., en-US). Default is en-US when not provided.
date_rangeAn object with from and to ISO‑8601 dates; clamp to a maximum of 90 days and fail if from > to.
Dependent Actions & Ordering (Optional) When an Action relies on another Action to produce a required input, state the ordering rule explicitly using exact action names.
  • Run ResolveUserIdByEmail immediately before SendWelcomeMessage to provide user_id.
  • When both are needed, run ResolveSkuByName before FindInventoryItems to provide a single sku_id.

​
Outputs & Mapping

Return only the fields the agent (or next Action) genuinely needs. Normalize raw payloads to stable, snake_case values. Checklist:
  • 3–6 purposeful fields beat dumping raw JSON.
  • Convert types (string numbers → numbers, null booleans → false).
  • Provide defaults or fail clearly if a critical field is missing.
  • Avoid leaking secrets or verbose internal traces.
Weak vs Strong mapping:
  • Weak: entire raw response forwarded.
  • Strong: { product_name, product_price, in_stock } extracted and typed.
Example mapping:
  • Raw: { "name": "Widget Pro", "price": "199.00", "availability": "in_stock" }
  • Mapped: { product_name: "Widget Pro", product_price: 199.0, in_stock: true }
Output Parameter Instruction Examples
OutputInstructions
summaryA concise HTML snippet suitable for rendering in the UI; must not contain scripts or inline event handlers.
matchesAn array of IDs ordered by relevance; include at most 25 items.
email_draftJSON with to_id, subject, and body_md. Use Markdown in body_md; do not embed images.

​
How Actions Work

Topics decide intent and sequence; Actions do the work. When a Topic is active, the agent chooses among allowed Actions, passes validated inputs, and consumes normalized outputs. Good Actions are:
  • Deterministic: same inputs → same outputs.
  • Composable: outputs feed cleanly into next steps.
  • Observable: failures are typed and explain what to do next (ask user for missing input, retry later, escalate).

​
Example Action Definition

ElementContent
NameGetOrderStatus
When to UseRetrieve the latest status, carrier, and ETA for an order using order_id; limited to the caller’s account.
Inputsorder_id (required, string, format: ord_XXXXXXXX), account_id (required, string), locale (optional, default en-US)
Outputsstatus (one of: processing, shipped, delivered, canceled), carrier (string), tracking_number (string|null), eta_date (ISO date|null)
Strong mapping example:
  • Raw upstream: { "order": { "state": "IN_TRANSIT", "eta": "2025-08-30", "carrier": "DHL", "track": "ABC123" } }
  • Mapped: { status: "shipped", carrier: "DHL", tracking_number: "ABC123", eta_date: "2025-08-30" }

​
Next Steps