Skip to main content

​
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 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 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 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

​
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

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

Last modified on May 21, 2026