AI Agents in Orchestration

18 min

Overview

AI Agents are a special type of component in Swimlane Turbine marked and managed separately from regular components. They appear as a dedicated section under the Orchestration menu and are used in playbooks to create intelligent automation workflows. By marking components as AI Agents, you create a focused library of specialized components that are easily discoverable and used in playbooks.

Why AI Agents Matter

AI Agents provide organizational benefits for managing your automation components:

Reusable Automation Blocks: Build once, use across multiple playbooks

Organized Component Library: Easily discover and manage specialized components

Consistent Naming and Categorization: Group related automation building blocks together

Accessing AI Agents

Access AI Agents through the main navigation:

Navigate to Orchestration in the left sidebar

Click on AI Agents to view all components marked as AI Agents

Empty State

When you first access the AI Agents section and no AI Agents have been created yet, an empty state screen appears with:

Title: "Get started with your first component"

Description: Information about components and their role in creating modular processes for playbooks

Action Buttons:

Browse the Swimlane content: Explore pre-built components from Swimlane's content library

Create a component: Start building your first component from scratch

Creating an AI Agent

Creating a New Component as an AI Agent

Create a new component directly from the AI Agents page:

From AI Agents Empty State:

Navigate to Orchestration > AI Agents

Click "Create a component" or "Browse the Swimlane content" from the empty state screen

When creating a component from the AI Agents page, the "Mark as AI Agent" checkbox is checked by default

From Components Page:

Navigate to Orchestration > Components

Click "Create a component" to start building a new component

The "Mark as AI Agent" checkbox is unchecked by default when creating from the Components page

Marking an Existing Component as an AI Agent

To convert an existing component into an AI Agent:

Navigate to Components:

Go to Orchestration > Components

Select an existing component to open it in the editor

Open Component Details:

The component editor opens with three main sections:

Left Panel: Add panel with Actions, Components, and AI Agents tabs

Center: Canvas area for building the component workflow

Right Panel: Component details panel

Access Summary Tab:

In the right panel, ensure the Summary tab is selected (alongside Assets, Data, and Associations tabs)

Enable AI Agent Checkbox:

Scroll to the Hero AI section in the Summary tab

Check the "Mark as AI Agent" checkbox

An information icon (ℹ️) next to the checkbox provides additional context

UI Changes: When you check this box, notice:

The panel title changes from "Component details" to "AI agent details"

The breadcrumbs at the top of the page update to include "AI agents"

If you uncheck it, the panel title and breadcrumbs revert to "Component"

Save Changes:

The component is automatically saved when you check the checkbox

The component appears in the AI Agents list and is available in the AI Agents tab when adding actions to playbooks

Component Requirements

Components must have a Name (required)

Optional components include:

Description (required if visibleToHeroAi is enabled)

Configuration Notes (for Hero AI context)

Schema/Interface (if using intents)

Using AI Agents in Playbooks

Adding an AI Agent to a Playbook

Add AI Agents to playbooks just like regular components:

Open a Playbook:

Navigate to Orchestration > Playbooks

Create a new playbook or open an existing one

Open Add Panel:

Click the "+" button on the canvas or use the Add Action panel

The Add panel appears on the left side with three tabs: Actions, Components, and AI Agents

Note: The Hero AI action has been moved to the top of the Actions tab for better visibility

Select AI Agents Tab:

Click on the AI Agents tab in the Add panel

This tab displays all components that have been marked as AI Agents

Search and Select:

Use the search box at the top of the AI Agents tab to find the AI Agent you want to use

Browse through the list of available AI Agents

Click on an AI Agent to add it to your playbook

Drag and Drop (Alternative):

Alternatively, drag an AI Agent from the AI Agents list directly onto the playbook canvas

Drop it on a playbook node or connection point

Visual Identification

When an AI Agent is added to a playbook canvas:

The node type displays as "AI Agent" instead of "component"

AI Agents have a distinct visual appearance with different icons compared to regular components

The title and icon are updated to reflect the AI Agent status

Connect them to other actions and triggers like regular components

AI Agent Properties

Summary Details

When viewing or editing an AI Agent component, the following properties are available:

Basic Information

Name: Component name (required)

Schema: Interface/intent name (if applicable, read-only)

Description: Component description (large text area)

Configuration Notes: Additional context for Hero AI (optional, large text area)

Source: Indicates if component is Custom or Swimlane Content (read-only, displays as "User-made" for custom components)

Hero AI

The Hero AI section in the Summary tab contains the following settings:

Mark as AI Agent:

Toggle that determines whether the component appears in the AI Agents list

When enabled, the component is categorized as an AI Agent and the panel title changes to "AI agent details" with breadcrumbs updated

Visible to Hero AI:

Toggle that makes the component discoverable and executable by Hero AI Companion

When enabled, Hero AI Companion uses the component during conversations

When enabled, the component appears in the Tools tab for Hero AI native actions

When disabled, removes the component as an available tool for Hero AI Companion

Requires Confirmation to Execute:

Only visible when "Visible to Hero AI" is enabled

Requires Hero AI Companion to ask for confirmation before executing this component in the Hero AI Companion chat

Understanding the Relationship

"Mark as AI Agent" = Categorizes the component as an AI Agent, making it appear in the AI Agents list and AI Agents tab in playbooks

"Visible to Hero AI" = Makes components available to Hero AI Companion and also makes components appear in the Tools tab for Hero AI native actions

These are independent settings—mark a component as an AI Agent without enabling "Visible to Hero AI", and vice versa.

Filtering and Searching

AI Agents List View

The AI Agents list supports filtering by:

Source: Custom or Swimlane Content

Interface: Filter by intent/interface name

Created By: Filter by component creator

Search Functionality

Use the search box at the top of the AI Agents tab to quickly find specific agents

Search filters components by name and other metadata

Clear search to reset filters

Best Practices

When to Use AI Agents

Reusable Automation Blocks:

Mark components that perform specific, well-defined tasks as AI Agents

Components that provide data or perform actions that might be useful in automation workflows

Specialized Tool Components:

Components that query external systems (TI providers, user directories, etc.)

Components that perform analysis or correlation

Components that handle communication or notifications

Components that create or update records

Hero AI Integration:

Components that should be discoverable by Hero AI Companion

Components that work well with conversational AI interfaces

Components designed to be orchestrated by Hero AI reasoning

Component Design for AI Agents

1. Clear Descriptions and Configuration Notes:

The description and configuration notes are critical - they help Hero AI understand when and how to use your AI Agent:

Description: Explain what the AI Agent does in clear, specific terms

✅ Good: "Queries multiple threat intelligence providers for IP addresses, domains, and file hashes. Returns consolidated threat scores and reputation data."

❌ Less effective: "Does threat intelligence"

Configuration Notes: Provide additional context about:

When the AI Agent should be used

What scenarios it is best suited for

Any limitations or considerations

Example: "Use this agent when analyzing observables from security alerts. Best for IP addresses and domains. Takes 5-10 seconds for multiple providers."

2. Proper Naming:

Use descriptive names that indicate the AI Agent's purpose

Follow consistent naming conventions (for example, "Query Threat Intelligence", "Check User Activity")

Avoid generic names like "Tool 1" or "Component A"

3. Well-Defined Schemas:

Input Schema: Clearly define what inputs the AI Agent expects

Use descriptive field names

Include field descriptions

Specify required vs. optional fields

Output Schema: Clearly define what outputs the AI Agent provides

Structure outputs logically

Include metadata that might be useful (for example, confidence scores, timestamps)

Make outputs easy for Hero AI to interpret and use

4. Documentation:

Document inputs, outputs, and behavior

Explain any AI-specific features or requirements

Provide examples of when to use the AI Agent

Document any dependencies or prerequisites

Building Your AI Agent Library

Think of AI Agents as building blocks for intelligent automation:

Start with Common Tasks: Identify repetitive tasks in your SOC workflows

Threat intelligence lookups

User context checks

System state queries

Communication tasks

Build Specialized Agents: Create focused AI Agents for specific purposes

One agent per tool/provider

One agent per type of analysis

One agent per communication channel

Organize and Categorize: Use consistent naming and descriptions

Group related agents (for example, "TI - VirusTotal", "TI - AbuseIPDB")

Use prefixes or tags for organization

Test Your AI Agents: Test your AI Agents in playbooks to ensure they work correctly

Verify that descriptions are clear and accurate

Ensure outputs are well-structured and useful

Integration with Hero AI

Hero AI Companion

Components with "Visible to Hero AI" enabled:

Discovered by Hero AI Companion during conversations

Executed by Hero AI when appropriate

Used in automated workflows suggested by Hero AI

Appear in the Tools tab for Hero AI native actions