Tools

Tools are declarative action definitions that agents can invoke during conversations. Unlike traditional function calls, tools in Agent Studio are configured via JSON without code changes.

Tool Structure

{
  "name": "save_meal",
  "description": "Log a meal the user consumed",
  "parameters": [
    { "name": "meal_type", "type": "string", "enum": ["breakfast", "lunch", "dinner"] },
    { "name": "dishes", "type": "array", "required": true }
  ],
  "actions": [
    { "type": "context.set", "key": "logged_meals[+]", "value": "params" },
    { "type": "webhook", "endpoint": "meal_log", "payload": { "meal": "params" } }
  ],
  "on_success": [
    { "type": "respond", "message": "Got it! I've logged your {{params.meal_type}}." }
  ],
  "on_failure": [
    { "type": "respond", "message": "Sorry, I couldn't save that meal." }
  ]
}

Parameters

Define what the LLM should extract from the conversation:

Property	Description
`name`	Parameter identifier
`type`	string, number, boolean, array, object
`required`	Whether the parameter is mandatory
`enum`	Allowed values (for strings)
`description`	Help text for the LLM
`default`	Default value if not provided

Action Types

Tools support 12 action types that can be chained together:

Context Actions

Action	Description	Properties
`context.set`	Store values in call context	`key`, `value`
`context.get`	Read values from context	`key`
`context.delete`	Remove values from context	`key`

{ "type": "context.set", "key": "user.preferences.theme", "value": "params.selected_theme" }
{ "type": "context.get", "key": "user.name" }
{ "type": "context.delete", "key": "temp.draft" }

Flag Actions

Action	Description	Properties
`flag.set`	Set a boolean flag	`flag`
`flag.clear`	Clear a boolean flag	`flag`

{ "type": "flag.set", "flag": "skip_confirmation" }
{ "type": "flag.clear", "flag": "needs_verification" }

Communication Actions

Action	Description	Properties
`respond`	Generate speech response	`message` or `message_key`
`handoff`	Transfer to another agent	`target`, `message` (optional)

{ "type": "respond", "message": "I've saved your meal successfully!" }
{ "type": "respond", "message_key": "context.dynamic_response" }
{ "type": "handoff", "target": "specialist_agent", "message": "Transferring you now..." }

Integration Actions

Action	Description	Properties
`webhook`	Call external API	`endpoint`, `payload`, `result_key`

{
  "type": "webhook",
  "endpoint": "save_meal",
  "payload": {
    "meal_type": "params.meal_type",
    "calories": "params.calories"
  },
  "result_key": "api_response"
}

Logic Actions

Action	Description	Properties
`conditional`	Branch based on condition	`condition`, `then`, `else`
`validate`	Validate parameters	`field`, `rule`, `error_message`
`transform`	Transform data	`input`, `expression`, `output`
`log`	Log data for debugging	`level`, `message`, `data`

Conditional Actions

Execute different actions based on a condition:

{
  "type": "conditional",
  "condition": "context.user_type === 'premium'",
  "then": [
    { "type": "respond", "message": "Welcome back, premium member!" }
  ],
  "else": [
    { "type": "respond", "message": "Welcome! Consider upgrading to premium." }
  ]
}

Conditions support JavaScript-like expressions with access to params, context, and flags.

Validation Actions

Validate input before processing:

{
  "type": "validate",
  "field": "params.email",
  "rule": "email",
  "error_message": "Please provide a valid email address"
}

Supported rules: required, email, phone, number, min_length, max_length, pattern

Transform Actions

Transform data using expressions:

{
  "type": "transform",
  "input": "params.items",
  "expression": "input.map(item => item.toUpperCase()).join(', ')",
  "output": "context.formatted_items"
}

Log Actions

Log data for debugging:

{
  "type": "log",
  "level": "info",
  "message": "Processing meal data",
  "data": "params"
}

Log levels: debug, info, warn, error

Variable Templates

Use {{path}} to reference context values in messages:

{{params.meal_type}} - Current tool parameters
{{user.id}} - User context
{{workflow.total}} - Shared workflow state
{{agents.meal.last}} - Agent-specific state

For action properties, use dot notation without braces:

params.meal_type - Reference parameter value
context.user.name - Reference context value

Array append with [+]:

{ "type": "context.set", "key": "meals[+]", "value": "params" }

Webhooks

Call external APIs using tenant-configured endpoints:

{
  "type": "webhook",
  "endpoint": "meal_log",
  "payload": {
    "user_id": "context.user.id",
    "meal": "params"
  },
  "result_key": "api_result"
}

Endpoints are defined in tenant settings (Settings > Webhook Endpoints) to keep tools portable across environments.

Success and Failure Callbacks

Define actions to run after tool execution:

{
  "on_success": [
    { "type": "context.set", "key": "last_action", "value": "'meal_saved'" },
    { "type": "respond", "message": "Done!" }
  ],
  "on_failure": [
    { "type": "log", "level": "error", "message": "Tool failed", "data": "error" },
    { "type": "respond", "message": "Something went wrong. Please try again." }
  ]
}

Action Chaining

Actions execute in order. Use chaining to build complex workflows:

{
  "actions": [
    { "type": "validate", "field": "params.email", "rule": "email" },
    { "type": "context.set", "key": "user.email", "value": "params.email" },
    {
      "type": "conditional",
      "condition": "params.subscribe === true",
      "then": [
        { "type": "webhook", "endpoint": "subscribe", "payload": { "email": "params.email" } },
        { "type": "flag.set", "flag": "subscribed" }
      ]
    },
    { "type": "respond", "message": "Your email has been saved!" }
  ]
}

Tools

On this page