The action lifecycle

Authoring an action is one continuous flow, not a set of disconnected screens. This page walks the whole path once, end to end, and links to the detail page for each step. Read it top to bottom the first time; come back to a single step when you need the specifics.

flowchart LR
  A["1. Write<br/>the action"] --> B["2. Define<br/>inputs"]
  B --> C["3. Test<br/>with Evals"]
  C --> D["4. Developer<br/>deploys handler"]
  D --> E["5. Publish<br/>the version"]
  E --> F["6. Observe in<br/>Conversations"]
  F -. "iterate" .-> A
  style A fill:#e8ecff,stroke:#1842ef,color:#0a0e1a
  style B fill:#e8ecff,stroke:#1842ef,color:#0a0e1a
  style C fill:#e8ecff,stroke:#1842ef,color:#0a0e1a
  style D fill:#fef3c7,stroke:#d97706,color:#0a0e1a
  style E fill:#1842ef,stroke:#1842ef,color:#ffffff
  style F fill:#d1fae5,stroke:#059669,color:#0a0e1a

1. Write the action

In Agent Studio → Actions, click Create Action and write the two prompts that tell the agent what the action does and when to reach for it: the Description and the Instructions. This is the highest-leverage step, the quality of these prompts is what decides whether the agent routes the right requests to your action.

Full field reference and prompting best practices: Authoring actions.

2. Define the inputs

On the User Input tab, define the schema, the fields the agent must extract from the conversation before it can run the action (an email, a role, a date range). Each field’s description doubles as a prompt: it tells the agent how to pull that value out of natural language.

Details: Defining inputs.

3. Test with Evals

Before anything goes live, open the Evaluations tab and confirm two things:

• The agent ties user intent to the right action (it doesn’t trigger the wrong one, or miss the trigger).
• The agent extracts the schema fields correctly from many phrasings of the same request.

Generate test prompts automatically or write your own, run them, and inspect the raw argument extraction. Re-run after every edit to the description, instructions, or schema.

Details: Evals.

4. Developer deploys the handler

Studio defines what the action does; your application code is the engine that runs it. A front-end developer takes the action key, the schema, and the expected output, implements the handler (the API call, navigation, or form submission), and ships it to production.

Wait for that deploy before you publish, so the action is never live to users without a working handler behind it.

Developer details: Connect actions in your app.

5. Publish the version

Every save creates a new version (v1, v2, v3…), but a version isn’t live until you publish it. Once the handler is deployed and your evals pass, select the version and click Publish. That version becomes Live and the agent starts using it in real conversations.

Rolling back

A rollback is just a publish. Open the version dropdown, select the previous known-good version, and click Publish, it immediately replaces the current Live version. Because old versions are never deleted, you can always return to one.

Details: Publishing & versioning.

6. Observe it in real conversations

Once live, the action shows up in Conversations:

• Filter by action. The conversation filter bar lets you narrow to chats where a specific action was triggered, so you can see exactly how it’s behaving in the wild.
• Inspect a single call. Open a conversation and click View Analysis under an agent message to see how the agent interpreted the request, which action it chose, and the arguments it extracted.
• Find demand for actions you haven’t built. Filter Conversation Signals → Agent Action Gap to surface requests where the user wanted something the agent had no action for — a ready-made backlog for step 1.

What you learn here feeds the next iteration: a missed trigger means tightening the instructions, a bad extraction means clarifying a field description, a wrong answer often means a Knowledge Base gap rather than an action bug.

The two coordinates of an action

Keep these straight and the rest follows:

	Configured in Studio (this flow)	Implemented in code
What the agent decides	When to call the action, what to extract	—
What actually happens	Mock response for testing	The real handler your developer deploys

You own steps 1–3, 5, and 6. Your developer owns step 4. Publish only when both halves are ready.