Connecting Actions: Workflows & APIs

By default, an Agent only performs chat completion — it generates text responses based on its instructions and conversation history. To let the Agent interact with external systems, trigger automated pipelines, or retrieve live data, you must attach Actions.

Navigating to the Actions Tab

1. Open the Agent in the Agent Builder.
2. In the left pane, click the Actions tab (next to Details).

Actions Tab Controls

When no Actions exist yet, the page shows an empty state illustration with the text "No actions available — Create your first action to get started."

Creating an Action

Click Create Action to open the creation form. This form appears as a new tab in the left pane.

Action Identity Fields

Action Type: API

Select API from the ActionType dropdown to connect an external HTTP endpoint as a tool.

The form is similar to the Workflow action type with the same configuration fields (Strict, Format Output, Render Output) and the same Input/Output Schema editors. The key differences:

Instead of a Workflow Id dropdown, you configure the HTTP endpoint details directly.

API Configuration Formats

The API endpoint can be configured in two formats:

HTTP Object

A structured form where you enter each part of the API call separately:

HTTP Curl

Alternatively, paste the full API call as a curl command:

curl -X POST https://api.example.com/verify \
  -H "Authorization: Bearer [[auth_secrets.auth_token]]" \
  -H "Content-Type: application/json" \
  -d '{"name": "{{customer_name}}", "id_number": "{{document_number}}"}'

Dynamic Parameter & Secret Injection

The API configuration supports dynamic value injection using double curly braces:

Using Secrets

You can securely reference sensitive values (like API keys or tokens) stored in your account using the secret placeholder syntax. This allows you to authenticate API calls without hardcoding credentials.

• Use plain secret names (letters, numbers, underscores) for maximum compatibility.
• For details on how to create and manage these values, see the Secrets Management Guide.

Using User-Provided Parameters

Any parameter that the Agent should dynamically populate from the user's message must be wrapped in double curly braces: {{parameter_name}}.

Crucially, the parameter names you use here must exactly match the property names defined in your Action Input Schema. If there is any mismatch (for example, using {{customer}} when your schema property is customer_name), the value will not be passed correctly to your action.

Best Practice: Always copy parameter names directly from your Input Schema when referencing them in your API configuration or workflow payloads. This ensures seamless, bug-free mapping between user input, the agent, and your action logic.

Example: Using User Input and Secrets in an API Request

Suppose you want to call an API that requires a user-provided customer_id and an API key stored as a secret (used in the headers).

1. Action Input Schema Example

{
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "string",
      "description": "The unique ID of the customer"
    }
  },
  "required": ["customer_id"]
}

2. API Configuration Example

{
  "method": "POST",
  "url": "https://api.example.com/customers/get",
  "headers": {
    "x-api-key": "{{secret.customer_api_secret.api_key}}",
    "Content-Type": "application/json"
  },
  "body": {
    "customer_id": "{{customer_id}}"
  }
}

3. Equivalent cURL Example

curl -X POST "https://api.example.com/customers/get" \
  -H "x-api-key: {{secret.customer_api_secret.api_key}}" \
  -H "Content-Type: application/json" \
  -d '{"customer_id": "{{customer_id}}"}'

• {{customer_id}} will be dynamically populated from the user’s input (must match your input schema).
• {{secret.customer_api_secret.api_key}} will be replaced with the value of api_key.

API Callback Passthrough

Whenever enable callback passthrough is enabled for an API action, the internal callback is skipped. This allows you to use the callback details to trigger an external callback endpoint when the operation is complete.

Callback Payload Instructions

The API should use the following variables to trigger the Vue agent's callback endpoint:

Required Attributes and Variables:

1. URL - {{VUE_CALLBACK.URL}}
2. Headers - {{VUE_CALLBACK.HEADERS}} (Returns a dictionary of headers)

{
    "x-client-id": "client_id_value",
    "x-client-name": "client_name_value",
    "x-packet-id": "current_job_id_value",
    "x-api-key": "api_key_value"
}

Header Keys as Individual Variables: All the above header keys are required for the callback to work. If needed, you can retrieve each value individually:

• CLIENT_ID: {{VUE_CALLBACK.HEADERS.CLIENT_ID}}
• CLIENT_NAME: {{VUE_CALLBACK.HEADERS.CLIENT_NAME}}
• PACKET_ID: {{VUE_CALLBACK.HEADERS.PACKET_ID}}
• API_KEY: {{VUE_CALLBACK.HEADERS.API_KEY}}

Requirements for the receiving endpoint:

• Must return a 2xx status code to acknowledge receipt.
• Must accept a Content-Type: application/json header.
• Your firewall must allow incoming requests from the service IP range.

Action Type: Workflow

Select Workflow from the ActionType dropdown to attach an existing Vue platform pipeline as a tool for your Agent.

Configuration Section

After selecting Workflow, the following configuration fields appear:

Workflow Selection

Input Schema

The Input Schema defines the JSON structure of parameters the Agent must extract from the user's message and pass to the Workflow.

If your action does not require any input parameters, you should use the following minimal schema:

{
  "type": "object",
  "properties": {}
}

Controls:

Default Input Schema template:

{
  "type": "object",
  "properties": {
    "parameter_1": {
      "type": "string",
      "description": "description_1"
    }
  },
  "required": [
    "parameter_1"
  ],
  "additionalProperties": false
}

The schema follows JSON Schema format. Each property's description is critical — the LLM reads it to understand what data to extract from the user's message for that parameter.

Example — A KYC Verification Workflow:

{
  "type": "object",
  "properties": {
    "customer_name": {
      "type": "string",
      "description": "Full legal name of the customer as it appears on their ID document"
    },
    "document_type": {
      "type": "string",
      "enum": ["passport", "drivers_license", "national_id"],
      "description": "Type of identity document being verified"
    },
    "document_number": {
      "type": "string",
      "description": "The unique number on the identity document"
    }
  },
  "required": ["customer_name", "document_type", "document_number"],
  "additionalProperties": false
}

Output Schema

The Output Schema defines the data structure the Workflow returns to the Agent after execution.

Controls:

Action Payload Structure

When triggering a workflow as an action from the agents framework, the action payload contains the following internal fields:

{
  "query": "<user query>",
  "chat_id": "<unique session ID>",
  "client_id": "<client identifier>",
  "user_id": "<user identifier>",
  "agent": "<agent configuration object>",
  "context": "<list of context messages>",
  "action_name": "<name of the workflow action>",
  "chat_state": "<current chat state object>",
  "parent_job_id": "<parent job ID for this processing step>",
  "payload": {
    "ui_context": {
      "urlContext": "<agent context in the UI>"
    }
  }
}

Field explanations:

• query: The current user query.
• chat_id: The unique identifier for the chat session.
• client_id: The client identifier.
• user_id: The user identifier.
• agent: The details of the agent (serialized).
• context: The list of context messages.
• action_name: The name of the action that was called.
• chat_state: The current chat state.
• parent_job_id: The job ID associated with the current processing step.
• payload: Contains the UI context.

previous_node_name = list(payload['payload'].keys())[0]
action_payload = payload["payload"][previous_node_name]["result"]

How the Agent Framework Handles Action Responses and Notifications

The agent framework automatically manages user notifications based on the duration of the action, for both APIs as actions and workflows as actions:

• Long-running jobs:
  If a workflow action or API action takes significant time to complete, the agent framework will automatically notify the user in the chatbot once the job finishes, including the action’s response.

• Short-running jobs:
  For quick actions, no notification is sent. The response is shown immediately in the chatbot as a regular message.

For workflows as actions, you also have the option to send additional custom notifications (such as progress updates or prompts for user intervention) during workflow execution. See the next section for details.

Custom Notifications from Your Workflow Action

In workflows triggered as an action, you have the ability to send notifications directly from within your workflow. These notifications will be displayed to the user in the chatbot interface.

This feature is especially useful in the following scenarios:

1. Long-running workflows:
   When a workflow takes significant time to complete, you can send progress notifications to keep the user informed about the current status.

2. User intervention required:
   If an intermediate step in the workflow requires the user to perform an action, such as verification, login, or approval - you can send a notification prompting the user. In these cases, your workflow should:

   1. Send a notification to the user via the chatbot, prompting them to complete the required step.
   2. Pause workflow execution and implement a polling mechanism within your workflow that periodically checks for the completion of the user event (e.g., by querying an API, database, or monitoring a status flag).
   3. Resume the workflow automatically once the user event is detected as complete.

   This approach allows your workflow to handle asynchronous, user-driven steps while providing real-time feedback and a seamless experience in the chatbot.

How to Send Notifications from Your Workflow

Use the following helper functions to send a notification to the user from within your workflow action:

import time
import requests

def send_notification(
    logger,
    title: str,
    body: str,
    chat_id: str,
    job_id: str,
    client_id: str,
    user_id: str,
    agent_id: str,
    agent_url: str,
    client_name: str = "",
    icon: str = "",
    url: str = "",
    priority: str = "medium"
) -> requests.Response:
    """
    Sends a notification to the chatbot user from within a workflow action.

    Args:
        logger: Logger instance for logging info.
        title: Notification title.
        body: Notification message body.
        chat_id: Chat session ID.
        job_id: Job or message ID.
        client_id: Client ID.
        client_name: (Optional) Client name.
        user_id: User ID.
        agent_id: Agent ID.
        agent_url: Base URL for the agent service.
        icon: (Optional) URL to an icon image.
        url: (Optional) URL to redirect the user.
        priority: (Optional) Notification priority (default: "medium").

    Returns:
        requests.Response: The HTTP response from the notification API.
    """
    payload = {
        "title": title,
        "body": body,
        "icon": icon,
        "url": url,
        "priority": priority,
        "chatId": chat_id,
        "agentId": agent_id,
        "messageId": job_id
    }
    notify_url = f"{agent_url}/api/v1/agents/notifications/publish"
    headers = {
        "Content-Type": "application/json",
        "x-client-id": client_id,
        "x-client-name": client_name,
        "x-user-id": user_id,
    }
    start = time.time()
    response = requests.post(notify_url, headers=headers, json=payload)
    logger.info(f"Notification sent: {payload} | Response: {response.text}")
    logger.info(f"Time to send notification: {time.time() - start:.2f}s")
    response.raise_for_status()
    return response

import os
import requests

def get_agent_host() -> str:
    """
    Retrieves the Agent host URL from Stephanie's service endpoints.
    Requires STEPHANIE_HOST and STEPHANIE_API_KEY to be set as environment variables.
    """
    stephanie_host = os.getenv('STEPHANIE_HOST')
    stephanie_api_key = os.getenv('STEPHANIE_API_KEY')
    if not stephanie_host or not stephanie_api_key:
        raise EnvironmentError("STEPHANIE_HOST and STEPHANIE_API_KEY must be set in environment variables.")
    url = f"{stephanie_host}/api/v1/configs/app_config/blox-service-endpoints"
    response = requests.get(url, headers={"Authorization": stephanie_api_key}, timeout=60)
    response.raise_for_status()
    return response.json()["data"]["agent"]

Usage Example:

agent_url = get_agent_host()

send_notification(
    logger=logger,
    title="Test Notification",
    body="Notification from Action Workflow",
    chat_id=action_payload["chat_id"],
    job_id=action_payload["parent_job_id"],
    client_id=action_payload["client_id"],
    user_id=action_payload["user_id"],
    agent_id=action_payload["agent"]["id"],
    agent_url=agent_url
)

How Strict Mode Works

Strict Mode (enabled via the Strict checkbox) is the primary guardrail for preventing the Agent from triggering Actions prematurely.

With Strict Mode ON (Recommended)

1. User says: "Verify my identity".
2. The Orchestrator recognizes the intent matches the Verify_KYC action.
3. The Orchestrator checks the Input Schema — it requires customer_name, document_type, and document_number.
4. The user only provided intent, not the required parameters.
5. The Agent responds: "I can help with identity verification. Could you please provide your full name, document type (passport, driver's license, or national ID), and document number?"
6. The user provides the missing data.
7. Now all required parameters are fulfilled — the Agent fires the Action.

With Strict Mode OFF

The Agent may attempt to invoke the Action with whatever parameters it can extract (or guess), even if some required fields are missing. This can lead to Action failures or incorrect behavior.

Per-Action Format & Render vs. Agent-Level Format & Render

It is important to understand that the action-level and agent-level Format/Render configurations serve different purposes and apply to different outputs:

These two scopes are completely independent:

• Enabling agent-level Format Responses does not affect Action outputs.
• Enabling action-level Format Output does not affect direct Orchestrator responses.
• You can enable one, both, or neither depending on your needs.

When a per-action Format/Render is enabled, it uses the same Formatter/Renderer Config (Model, Temperature, Instructions) defined on the Details tab.

Action Description

Every action—whether it is an API or a Workflow—should include a clear, concise description.
This description is provided to the language model (LLM) as the "tool description", and is critical for:

• Helping the LLM decide when to use this action versus others
• Guiding the LLM to route user queries to the correct action
• Improving the quality and relevance of the agent's responses
• Explaining how the input schema for the action should be constructed based on context
• Providing any other information that is specific to the action.

A well-written action description directly impacts the agent's behavior and the overall user experience.

Example:

"Verifies a user's identity document (passport, driver's license, or national ID) against the provided customer details.
To trigger this action, the user must supply the full name, document type, and document number as specified in the input schema."

Best Practices:

• Write descriptions that are specific about what the action does and when it should be used.
• Clearly state what information the user must provide to trigger the action (reference required input parameters).
• Avoid vague or generic descriptions.
• If the action is specialized (e.g., "Verify a user's KYC document"), state that clearly.
• Ensure orthogonality: Each action should have a distinct, non-overlapping purpose. If multiple actions can be triggered by similar user queries, the LLM may not reliably choose the correct one, leading to degraded performance. Design your actions so that each one addresses a unique use case or intent.

Saving and Deploying Actions

After filling in all fields and defining your schemas:

1. Click the Create button at the top of the Create Action form.
2. The Action appears in the Actions list.
3. To deploy all Actions at once, click Deploy All on the Actions tab.
4. Alternatively, save the entire Agent via the Update button in the top bar.

Testing Actions via Chat

After creating and deploying an Action:

1. Switch to the Chat tab in the right pane.
2. Start a + New Session for a clean testing environment.
3. Type a message that matches the Action's purpose (e.g., "I need to verify my identity").
4. With Strict Mode on, observe the Agent:
   • Recognizing the intent.
   • Checking for missing parameters.
   • Prompting the user to provide them.
   • Executing the Action once all parameters are collected.
5. Verify the output format and rendering quality.

Troubleshooting