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", "path": "logged_meals[+]", "value": "params" },
    {
      "type": "api_call",
      "url": "{{tenant.settings.endpoints.meal_log}}",
      "method": "POST",
      "body": { "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, integer, 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	`path`, `value`
`context.get`	Read values from context	`path`
`context.delete`	Remove values from context	`path`

{ "type": "context.set", "path": "user.preferences.theme", "value": "params.selected_theme" }
{ "type": "context.get", "path": "user.name" }
{ "type": "context.delete", "path": "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`
`handoff`	Transfer to another agent	`target_agent`, `message` (optional)

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

Integration Actions

Action	Description	Properties
`api_call`	Call external HTTP API	`url`, `method`, `body`, `headers`, `response_path`, `retry_count`, `retry_delay`, `on_error`

{
  "type": "api_call",
  "url": "https://your-api.com/meals",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{user.auth_token}}"
  },
  "body": {
    "user_id": "{{user.id}}",
    "meal_type": "{{params.meal_type}}",
    "calories": "{{params.calories}}"
  },
  "response_path": "workflow.api_response",
  "timeout": 30,
  "retry_count": 3,
  "retry_delay": 0.5,
  "on_error": "fail"
}

API Call Properties

Property	Type	Default	Description
`url`	string	required	Full URL or template (e.g., `{{tenant.settings.endpoints.meal_log}}`)
`method`	string	`POST`	HTTP method (GET, POST, PUT, PATCH, DELETE)
`body`	object	-	Request body (for POST/PUT/PATCH)
`headers`	object	-	HTTP headers
`timeout`	number	30	Request timeout in seconds
`response_path`	string	-	Context path to store the response
`retry_count`	number	3	Number of retries on failure
`retry_delay`	number	0.5	Delay between retries in seconds
`on_error`	string	`fail`	`"fail"` to fail the tool, `"continue"` to proceed

Logic Actions

Action	Description	Properties
`conditional`	Branch based on condition	`condition`, `then_actions`, `else_actions`
`validate`	Validate parameters	`rules`
`transform`	Transform data	`input_path`, `output_path`, `transform_type`, `transform_config`
`log`	Log data for debugging	`level`, `log_message`

Conditional Actions

Execute different actions based on a condition:

{
  "type": "conditional",
  "condition": "context.user_type === 'premium'",
  "then_actions": [
    { "type": "respond", "message": "Welcome back, premium member!" }
  ],
  "else_actions": [
    { "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",
  "rules": [
    { "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_path": "params.items",
  "transform_type": "map",
  "transform_config": { "expression": "item.toUpperCase()" },
  "output_path": "workflow.formatted_items"
}

Log Actions

Log data for debugging:

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

Log levels: debug, info, warn, error

Variable Templates

Use {{path}} to reference context values in messages and action properties:

{{params.meal_type}} - Current tool parameters
{{user.id}} - User context (from user_context passed at call dispatch)
{{user.auth_token}} - Auth token for API calls
{{workflow.total}} - Shared workflow state
{{agents.meal.last}} - Agent-specific state
{{tenant.settings.endpoints.meal_log}} - Tenant-configured endpoints

Array append with [+]:

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

External API Calls

Call external APIs using the api_call action with full control over the request:

{
  "type": "api_call",
  "url": "https://your-api.com/meals",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer {{user.auth_token}}"
  },
  "body": {
    "user_id": "{{user.id}}",
    "meal": "{{params}}"
  },
  "response_path": "workflow.api_result",
  "retry_count": 3
}

For portable tools across environments, store API base URLs in tenant settings and reference them via templates:

{
  "type": "api_call",
  "url": "{{tenant.settings.endpoints.meal_api}}/meals",
  "method": "POST",
  "body": { "meal": "{{params}}" }
}

See the Backend Integration Guide for authentication patterns and security best practices.

Success and Failure Callbacks

Define actions to run after tool execution:

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

Action Chaining

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

{
  "actions": [
    {
      "type": "validate",
      "rules": [{ "field": "params.email", "rule": "email" }]
    },
    { "type": "context.set", "path": "user.email", "value": "params.email" },
    {
      "type": "conditional",
      "condition": "params.subscribe === true",
      "then_actions": [
        {
          "type": "api_call",
          "url": "{{tenant.settings.endpoints.subscribe}}",
          "method": "POST",
          "body": { "email": "{{params.email}}" }
        },
        { "type": "flag.set", "flag": "subscribed" }
      ]
    },
    { "type": "respond", "message": "Your email has been saved!" }
  ]
}

Tools

On this page