Atlas Actions Documentation

Overview

Atlas Actions allows you to connect external APIs and services to your AI agent, enabling it to fetch real-time information during conversations. When triggered, the agent makes an HTTP request to your specified endpoint and uses the response data as context to provide more accurate and informed answers.

Options to create a new tool.

Use Cases

Retrieve customer order status and tracking information

Query product inventory and availability

Access user account details and preferences

Fetch real-time data from internal systems

Pull information from third-party services

Check support ticket status

Validate business rules or constraints

Configuration

Name

A unique identifier for your tool. Choose a descriptive name that clearly indicates its purpose (e.g., "Customer Order Lookup", "Inventory Checker", "User Profile API").

Description

Define when and how the AI agent should use this tool. The description acts as instructions for the agent, helping it understand:

When to trigger: What user queries or conversation contexts should activate this tool

What it provides: The type of information the tool returns

How to use it: Any specific conditions or parameters needed

Example descriptions:

"This tool runs when the user asks for information about customer orders. It provides order status, tracking details, and delivery estimates."

"Use this tool when users inquire about product availability. It returns current stock levels and estimated restock dates."

"Trigger this tool when users ask about their account settings or preferences. It retrieves user profile data and subscription status."

URL

The HTTP endpoint that will receive the request. Must be a valid, publicly accessible URL.

Timeout (milliseconds)

Maximum time (in milliseconds) to wait for the response before timing out.

Default: 30000ms (30 seconds)

Synchronous Mode

When enabled, the AI agent waits for the response before continuing the conversation.

Options:

Enabled (Wait for response): Agent pauses until receiving the data, ensuring it has the information before responding to the user

Disabled: Agent continues the conversation without waiting (use for fire-and-forget scenarios)

Recommended: Keep enabled for most use cases where the returned data is essential for the response.

Strict Mode

Controls parameter validation enforcement.

Options:

Enabled: Enforces strict validation on all defined parameters

Disabled: Does not enforce strict parameter validation (more flexible, but potentially less predictable)

Parameters

Define input parameters that the AI agent should extract from the conversation and send to your API.

Click "+ Add Property" to add a new parameter

Adding a Parameter

When you click "+ Add Property", configure the following fields:

Name

The parameter key name that will be sent in the API request body.

Format: parameterName (use camelCase or snake_case)

Examples: order_id, customerEmail, product_sku, user_id

Type

The data type for this parameter. Select from the dropdown:

String: Text values (e.g., "ORD-12345", "john@example.com")

Number: Numeric values (e.g., 42, 3.14)

Boolean: True/false values

Array: List of values

Object: Nested JSON object

Description

Instructions for the AI agent on how to identify and extract this value from the conversation.

Best practices:

Be specific about the format or pattern (e.g., "The order number in format ORD-XXXXX")

Mention where users typically provide this information

Include examples of valid values

Describe what the parameter represents

Example descriptions:

"The customer's order number, usually mentioned in the format ORD-12345"

"The user's email address that they use for their account"

"The product SKU or item code the customer is asking about"

"The tracking number provided by the shipping carrier"

Default Value

An optional default value to use if the AI agent cannot extract this parameter from the conversation.

Examples:

For status parameter: "active"

For limit parameter: 10

For include_archived parameter: false

Note: Leave empty if no default value should be used.

Required

Check this box if this parameter is mandatory for the API endpoint to function properly.

When checked:

The AI agent will only trigger the tool if it can extract this parameter

The tool call will fail if the required parameter is missing

When unchecked:

The tool will be called even if this parameter is not found

Optional parameters provide flexibility for various conversation contexts

After configuring, click Apply to add the parameter, or Cancel to discard changes.

HTTP Headers

Add custom HTTP headers to include with each API request.

Click "+ Add Header" to add a new header

Adding an HTTP Header

When you click "+ Add Header", configure the following fields:

Key

The HTTP header name.

Common header keys:

Content-Type

Authorization

X-API-Key

X-Client-ID

Accept

User-Agent

Value

The value for this HTTP header.

Example values:

For Content-Type: application/json

For Authorization: Bearer your-api-token-here

For X-API-Key: your-api-key-here

For Accept: application/json

Security note: Avoid hardcoding sensitive tokens directly in headers if possible. Use the OAuth authentication feature for secure token management.

Header Example Configuration

Key: Content-Type
Value: application/json

Key: X-API-Key
Value: your-api-key-here

After configuring, click Apply to add the header, or Cancel to discard changes.

Authentication

Configure OAuth credentials for secure authentication with your API endpoint.

OAuth Client Credential Connection

Select an existing OAuth credential or create a new one if your API requires OAuth 2.0 Client Credentials authentication. Currently, Basic Authentication method is supported.

Click "+ Create New" to set up a new OAuth credential

Note: If your endpoint doesn't require authentication, leave this set to "None".

Creating an OAuth Client Credential

When you click "+ Create New", you'll configure the following:

Connection Name *

A descriptive name for this OAuth credential connection (e.g., "My OAuth Connection", "Production API Auth").

Client ID *

The OAuth client identifier provided by your OAuth server or API provider.

Format: your-client-id

Client Secret *

The OAuth client secret provided by your OAuth server or API provider. This is a sensitive credential that should be kept secure.

Format: your-client-secret

Authentication Method *

The method used to authenticate with the OAuth token endpoint.

Currently supported: Basic Authentication

Basic Authentication sends the client credentials in the HTTP Authorization header using the format: Authorization: Basic base64(client_id:client_secret)

Token Endpoint *

The URL of the OAuth server's token endpoint where the client credentials will be exchanged for an access token.

Format: https://auth.example.com/oauth/token

Requirements:

Must be a valid HTTPS URL

Should be the token endpoint provided in your OAuth provider's documentation

Scopes

Optional OAuth scopes that define the level of access requested. Multiple scopes can be added.

Format: Space-separated or individual scope entries

Example scopes:

read:orders

write:inventory

user:profile

Note: Available scopes depend on your OAuth provider's API. Leave empty if no specific scopes are required.

Audience

The intended audience for the access token, typically the API identifier or resource server URL.

Format: https://api.example.com

Note: This field is required by some OAuth providers (like Auth0) to identify which API the token is intended for. Check your OAuth provider's documentation to see if this is needed.

OAuth Flow

Once configured, the OAuth Client Credentials flow works as follows:

When the tool is triggered, the system automatically requests an access token from the Token Endpoint

The access token is obtained using the Client ID and Client Secret with Basic Authentication

The access token is included in the tool request's Authorization header

Tokens are automatically refreshed when they expire

This ensures secure, authenticated access to your API endpoint without manual token management.

Best practices:

Return clear, structured data that's easy for the AI to understand

Include relevant context that helps the AI formulate better responses

Use consistent response formats across different API calls

Handle errors gracefully with descriptive error messages

Error Handling

If your tool:

Times out (exceeds the configured timeout)

Returns a non-2xx HTTP status code

Returns invalid JSON

The AI agent will handle the error gracefully and may inform the user that the information is temporarily unavailable.

Atlas Actions triggering

Atlas Actions Documentation#

Overview#

Use Cases#

Configuration#

Name#

Description#

URL#

Timeout (milliseconds)#

Synchronous Mode#

Strict Mode#

Parameters#

Adding a Parameter#

Name#

Type#

Description#

Default Value#

Required#

HTTP Headers#

Adding an HTTP Header#

Key#

Value#

Header Example Configuration#

Authentication#

OAuth Client Credential Connection#

Creating an OAuth Client Credential#

Connection Name *#

Client ID *#

Client Secret *#

Authentication Method *#

Token Endpoint *#

Scopes#

Audience#

OAuth Flow#

Error Handling#

Atlas Actions Documentation

Overview

Use Cases

Configuration

Name

Description

URL

Timeout (milliseconds)

Synchronous Mode

Strict Mode

Parameters

Adding a Parameter

Name

Type

Description

Default Value

Required

HTTP Headers

Adding an HTTP Header

Key

Value

Header Example Configuration

Authentication

OAuth Client Credential Connection

Creating an OAuth Client Credential

Connection Name *

Client ID *

Client Secret *

Authentication Method *

Token Endpoint *

Scopes

Audience

OAuth Flow

Error Handling