--- title: Hero AI Native Action slug: hero-ai-native-action docTags: createdAt: 2025-08-11T11:13:48.000Z --- The Hero AI native action integrates AI-driven workflows directly into your orchestration processes. It uses **Amazon Bedrock** for inference and eliminates complex scripting and manual transformations for generative AI steps in playbooks and components. ## Choose Your Path | Goal | Go to | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | Configure prompt and model | [Prompt Tab](https://docs.swimlane.com/hero-ai-native-action#prompt-tab) | | Pick a Bedrock model | [Model Selection](https://docs.swimlane.com/hero-ai-native-action#model-selection) | | Saved model unavailable | [When the Saved Model Is Unavailable](https://docs.swimlane.com/hero-ai-native-action#when-the-saved-model-is-unavailable) | | Add tools | [Tools Tab](https://docs.swimlane.com/hero-ai-native-action#tools-tab) | | Keep tool names in limit | [Tool Name Length](docId\:C4CKmT7fHXgjBtlXxOOC2) | | Test before deploy | [Testing and Validation](https://docs.swimlane.com/hero-ai-native-action#testing-and-validation) | | Define JSON output | [Defined Output Format (JSON)](docId\:C4CKmT7fHXgjBtlXxOOC2) | | Default model | **Use Default Model** is **Claude Haiku 4.5** — [Hero AI Models](docId\:C1LdFGRmok-7Z2Nei_28b) | ## Introduction The **Hero AI** native action enables orchestrators to integrate AI-driven workflows directly into playbooks and components. Define prompts in natural language, use field replacement to inject dynamic data, and configure tools that Hero AI calls autonomously to gather information and make decisions. **Key Capabilities:** - **Natural Language Prompts**: Express what you want to accomplish, not how to accomplish it - **Dynamic Field Replacement**: Integrate playbook data into prompts using field replacements - **Autonomous Tool Selection**: Configure tools and let Hero AI decide when and how to use them - **Intelligent Reasoning**: Hero AI analyzes context and makes decisions similar to a skilled analyst - **Adaptive Operations**: Workflows adapt to different scenarios based on available context and data - **Model Selection**: Choose a specific Amazon Bedrock model for the action, or leave **Use Default Model** for **Claude Haiku 4.5** on Swimlane-managed routing ## Key Interface Elements ### Prompt Tab - **Prompt Input Field**: Define the text prompt sent to Hero AI for processing. Use a natural language query or command relevant to the desired Hero AI action. This is a required field. If left blank, an error message appears. - **Add Playbook Property**: Adds dynamic properties from a playbook, enabling Hero AI to reference real-time data during execution. For example, adding the playbook property for security alerts makes Hero AI aware of specific incidents from your system. - **Contains Sensitive Data**: Marks prompts that contain sensitive information. When enabled, the prompt data is handled according to your organization's data protection policies. ### Model Selection Starting in **Turbine 26.2.0**, the **Prompt** tab includes a **Model Selection** section below the prompt editor. | Field | Description | | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Model** | Optional. Select which Bedrock model Hero AI uses for this action. Placeholder: **Use Default Model**. When empty, Swimlane-managed routing uses **Claude Haiku 4.5**. See [Hero AI Models](docId\:C1LdFGRmok-7Z2Nei_28b). | **How to select a model:** 1. Open the **Hero AI** action on the canvas and go to the **Prompt** tab. 2. Under **Model Selection**, open the **Model** drop-down. 3. Optionally type in **Filter options...** to search the list. 4. Select a model, or leave the field empty to use **Use Default Model** (**Claude Haiku 4.5** on Swimlane-managed routing). :::hint{type="info"} **Use Default Model** is **Claude Haiku 4.5**, not **Claude Sonnet 4.5**. Starting in **Turbine 26.4.0**, **Agents** default to **Claude Sonnet 5** (fallback **Sonnet 4.5**). [Hero AI Companion](docId\:crQKFVnGpCz_wJ8xtHDs7) stays on **Sonnet 4.5**. Hover the info icon next to **Model Selection** for [Hero AI Models](docId\:C1LdFGRmok-7Z2Nei_28b). ::: **Available models** Models are loaded from your account configuration. The list can vary by deployment and entitlement. Examples shown in the product include: | Model | Tokens per credit | Notes | | ----------------------- | ----------------- | ----------------------------------------------------------------- | | **Haiku 4.5** | 300 | Aligns with default Native Action routing (**Use Default Model**) | | **Sonnet 4.5** | 100 | Higher-capability Claude Sonnet tier | | **Sonnet 4.6** | 100 | Higher-capability Claude Sonnet tier | | **Opus 4.5** | 60 | Highest-capability Claude Opus tier | | **Opus 4.6** | 60 | Highest-capability Claude Opus tier | | **OpenAI gpt-oss-20b** | 4500 | Open-weight option (not on every instance) | | **OpenAI gpt-oss-120b** | 2200 | Larger open-weight option (not on every instance) | | **Qwen3 32B** | 2200 | Qwen option (not on every instance) | Under **Model Selection**, each available model can show a secondary line under the model name: `{provider} / {N} Tokens per Credit` (for example `Claude / 300 Tokens per Credit`). Higher **Tokens per Credit** means more tokens of that model equal one credit. **Sonnet 5** is not offered in the Native Action **Model** drop-down in Turbine 26.4. Starting in **Turbine 26.4.0**, **Agents** (plan generation, playbook builder, component agents, and related code-agent traffic) default to **Sonnet 5** when Custom LLM is off, with **Sonnet 4.5** as fallback. **Hero AI Companion** continues to use **Sonnet 4.5**. If Custom LLM is on and the Medium default is Sonnet 5, Companion does not work. Keep Medium on Sonnet 4.5 when Companion is required. You cannot configure Agent or Companion routing in the UI. When you select a model, the choice applies to both playbook runs and **Test** runs for that action. For residency by Swimlane instance, see [Hero AI Models](docId\:C1LdFGRmok-7Z2Nei_28b) in [Hero AI Models](docId\:C1LdFGRmok-7Z2Nei_28b). ### When the Saved Model Is Unavailable Starting in **Turbine 26.2.0**, a Hero AI native action can keep a **modelId** that is no longer valid for the current account — for example after you change [Custom LLM](docId\:Deoy-K3jmcpdm-c-IKRQ4) provider settings, or after you copy an action into an account where that model is not offered. | Layer | Behavior | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **At run time** | Before each execution, Turbine checks whether the saved **modelId** exists in the current available models list. If it does not, the action uses the **Small** model — the default model for Hero AI Native Action (typically **Claude Haiku 4.5** under Swimlane-managed routing). The playbook run continues instead of failing on an invalid model. | | **In the action dialog** | When you open **Model Selection**, if the saved model is not in the list, the UI shows **Previously Selected Model is not available** in red. Select a new model from the drop-down, or clear the selection to use **Use Default Model**. | **Common scenarios** | Scenario | What to expect | | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | Toggle **Custom LLM** between default Swimlane and LiteLLM | Existing actions may still store a model from the previous provider. Runs fall back to the **Small** model until you update the action. | | Copy a playbook or action to another account or tenant | A model valid in the source account may not exist in the target. Same fallback and UI message apply. | | Change LiteLLM or Custom Bedrock model names | Actions that referenced removed model IDs fall back at run time; update the action when you see the unavailable-model message. | :::hint{type="info"} After changing **Custom LLM** settings, open affected Hero AI native actions and confirm **Model Selection**. See [Custom LLM](docId\:Deoy-K3jmcpdm-c-IKRQ4) for how provider changes affect Hero AI routing. ::: - **maxOutputTokens Parameter**: The `maxOutputTokens` field sets the maximum number of **output tokens** Hero AI uses when generating a response. This parameter controls the output token limit, not input tokens. A token ranges from one character to a word. The default value of 1024 provides a balanced level of detail. Adjust based on your needs. The current maximum value is 8192 output tokens. - **Test Button and Previous Playbook Run Drop-down**: After entering your prompt, click **Test** to see how Hero AI responds. Select a previous playbook run from the **From previous run** drop-down menu to test the prompt with historical data. The drop-down lists previous runs with timestamps, showing how Hero AI handles various datasets from different runs. - **Error Handling**: If a required field is missing or there is an issue with the prompt, error information appears in the test result output section. Review the error details to troubleshoot any issues. :::hint{type="info"} Prompt formatting may be lost if you navigate to the **Tools** or **Outputs** tabs without saving. To preserve formatting, save your changes before switching tabs. If formatting is lost, close the action configuration dialog and reopen it to restore the original formatting ::: ### Tools Tab The **Tools** tab configures tools that Hero AI uses to help address your prompt. Hero AI calls these tools at its discretion to gather relevant data and insights to help it make decisions. The **Tools** tab displays all components and AI agents available in your tenant. Select from this list which tools to configure for that instance of the native action. Hero AI analyzes your prompt and automatically determines which tools to call based on what your prompt asks for, what each tool's description says it does, and the context available in your playbook. :::hint{type="info"} Tools must have a valid **Description** to help Hero AI understand when and how to use them. Components without descriptions may not be used effectively by Hero AI. There are no hard limits to how many tools can be configured for each native action, but configure only the tools that are relevant to your specific task. More tools lead to decreased accuracy, so choose only what you need. ::: ### Tool Name Length When Hero AI calls a tool, the model receives the **tool name**. Flagship models (Haiku and Sonnet) allow names up to **128** characters. | Models | Maximum Tool Name Length | | ----------------------- | ------------------------ | | Haiku and Sonnet | **128** characters | | OpenAI gpt-oss and Qwen | **64** characters | Some models use a lower **64**-character limit. Names longer than that limit can cause LLM invocation errors when the Native Action calls the tool. Shorten the name. Do not add client prefixes such as `mcp__server__tool`. Turbine does not add those prefixes. Test playbooks that use MCP tools before you run them routinely. This limit is for **tool names** passed to the model. It is separate from the **50**-character **component name** limit. See [Components](https://docs.swimlane.com/components). ### Adding and Configuring Tools 1. **Add a Tool**: Click the **Add a Tool** button to open the tool selection interface. 2. **Edit Tools Dialog**: The **Edit Tools** dialog displays all available tools with the following information: - **Tools**: The name of the tool with its icon - **Description**: A description of what the tool does (required for effective tool usage) - **Interface**: The interface version associated with the tool (if applicable) 3. **Select Tools**: - Use the search bar to filter available tools - Select tools by checking the checkbox next to each tool you want to include - Select multiple tools - The dialog shows "X selected / Y total" at the bottom to track your selections 4. **Apply Changes**: Click **Apply** to save your tool selections, or **Cancel** to discard changes. 5. **Edit Tools**: After tools are configured, click **Edit Tools** to add additional tools or remove existing ones. Tools are optional. Add tools only when they provide value to your specific use case. Hero AI automatically determines when and how to use the configured tools during prompt execution. :::hint{type="info"} All components and AI agents in your tenant are available as tools in Hero AI native actions. Tools can be either regular components or Turbine AI agents. To ensure components work effectively as tools, provide clear **Description** fields that explain what the tool does and when to use it—this is essential for Hero AI to understand when to call the tool. Also ensure well-defined input/output schemas so Hero AI understands what data to provide and what to expect. ::: ### Outputs Tab The **Outputs** tab shows **Action Outputs** (schema for the action) and, when **Hero AI Defined Output** is enabled, an **Additional Options** panel on the right for **Output Format**. ### Output Format | Output Format | Behavior | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | **None** | Default. Free-text response in `result.generatedText`, plus metadata and related fields. | | **JSON** | Structured output. Hero AI returns data shaped to the schema you define under **Response**. **Generated Text** is not part of the JSON result schema. | ### Default outputs (Output Format = None) - **result**: AI-generated response and metadata: - **Request Id** (`result.requestId`) - **Generated Text** (`result.generatedText`) - **Finish Reason** (`result.finishReason`) — `"Stop"` for natural completion, `"length"` if truncated by token limit - **Prompt Tokens** / **Response Tokens** - **turns** / **configuredTools** when present - **error**: Error information if the action fails :::hint{type="info"} When referencing outputs in downstream actions, use the full namespace path. For example, to access the generated text, use `result.generatedText` rather than just `generatedText`. ::: **Using Outputs in Downstream Actions:** :::BlockQuote *# Example: Using Hero AI output in a conditional action* condition: result.finishReason == "Stop" && result.responseTokens \< 500 ::: :::BlockQuote *# Example: Using generated text in a notification* message: "AI Analysis: " ::: ### Defined Output Format (JSON) Starting in **Turbine 26.4.0**, set **Output Format** to **JSON** when downstream actions need reliable structured fields instead of parsing free text. **Layout when JSON is selected** | Area | What you see | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Action Outputs** (left) | `result` with fixed fields **Request Id**, **Finish Reason**, **Prompt Tokens**, **Response Tokens**, plus editable **Response** (object) for your schema | | **Additional Options** (right) | **Output Format** set to **JSON** | **How to configure** 1. Open the **Hero AI** action and go to the **Outputs** tab. 2. Under **Additional Options**, set **Output Format** to **JSON**. 3. Under **Response**, add properties (and nested objects if needed). Give each property a clear description so the model knows what to return. 4. Optionally open **Schema Property Configuration** (gear) on a property for the **Constraints** tab and related options (for example mark required). When **Output Format** is **JSON**, **Mark as Sensitive** is not available on the result or on defined JSON properties. Other output formats still allow **Mark as Sensitive** when obfuscation is enabled. See [Property constraint priority](docId\:C4CKmT7fHXgjBtlXxOOC2). 5. Click **Apply**, then save the playbook. 6. Use **Test** on the **Prompt** tab to validate that structured values appear under `result.response`. **Fixed vs editable fields (JSON)** | UI label | Path | Notes | | ------------------- | ----------------------- | ----------------------------------------------------------- | | **Request Id** | `result.requestId` | System field | | **Finish Reason** | `result.finishReason` | System field | | **Prompt Tokens** | `result.promptTokens` | System field | | **Response Tokens** | `result.responseTokens` | System field | | **Response** | `result.response` | Editable object — define properties and nested objects here | Example: a **Response** object with nested **data** (`id`, `name`, `email`, …) is referenced downstream as `result.response.data.email`. ### Property constraint priority On **Schema Property Configuration** → **Constraints**, Turbine does not treat all constraints as equal. If more than one constraint is set on the same property, the model follows this order: 1. **Const** or **Enum** (highest). You cannot use **Const** and **Enum** on the same property. 2. **Format** (lower). Used when **Const** and **Enum** are not set. Do not combine **Const** or **Enum** with **Format** on the same property. If both are set, the action can still succeed and `result.response` uses the **Const** (or **Enum**) value. **Format** is not enforced in that case. ### Defined JSON Output Limitations Test JSON output on the **Prompt** tab before you rely on it in production. The following schema and structured-output issues come from the language model, not from Turbine: - **Schema too complex.** A large, complex, or nested **Response** schema (many optional properties, or large tool or component input schemas) can return schema-too-complex, schema-grammar, or other compilation errors from the model. Simplify the JSON, reduce the object size, mark properties **required**, and mark required inputs on attached tools or components. - **Model differences.** Structured JSON is not equally reliable on every model. **Sonnet 4.5**, **gpt-oss**, and **Qwen** models can fail to return schema-shaped output even when the same prompt succeeds on other models. If JSON output is unreliable, switch models and retest. Turbine also has these product limits: - **No schema-conformance check.** Turbine does not currently verify that the model response matches your schema. Confirm `result.response` in **Test** before you map fields downstream. - **Mark as Sensitive.** JSON output does not support **Mark as Sensitive** on the result or on defined JSON properties. ### Required properties in nested schemas If a **nested** property must appear in the Hero AI response, mark that property **and every parent object** as **required**. Marking only the leaf as required is not enough. Example: for `result.response.alertInformation.userInformation.detectedTime` to be present reliably, mark **alertInformation**, **userInformation**, and **detectedTime** (and any intermediate objects) as required — not only **detectedTime**. :::hint{type="info"} Optional (non-required) properties may still be omitted from `result.response` even when values appear in the prompt. Prefer required on the fields your downstream mappings depend on. ::: :::hint{type="info"} Switching from **JSON** back to **None** restores free-text **Generated Text** behavior. The UI caches your JSON schema while you toggle formats in the dialog so you can switch back without rebuilding the schema from scratch. ::: **Using structured outputs downstream:** :::BlockQuote *# Example: Use a nested field from defined JSON output* condition: result.response.data.status == "active" ::: :::hint{type="warning"} Defined output requires the **Hero AI Defined Output** feature to be enabled for the account. If **Additional Options** is not visible on the **Outputs** tab, contact your Swimlane administrator. ::: ## How to Use the Hero AI Action 1. Open your playbook in the Turbine Canvas and drag the **Hero AI** action from the **Add Panel** into your canvas. 2. **Configure the Prompt**: Write your custom prompt in the **Prompt** tab. Use **Add Playbook Property** to insert dynamic data, mark sensitive data if needed, optionally select a **Model** under **Model Selection**, and adjust `maxOutputTokens` (default 1024, max 8192). 3. **Configure Tools** (Optional): Navigate to the **Tools** tab, click **Add a Tool**, select relevant tools from all available components (ensure tools have clear descriptions), and click **Apply**. 4. **Configure Outputs** (Optional): On the **Outputs** tab, leave **Output Format** as **None** for free text, or choose **JSON** and define properties under **Response** for structured output. 5. **Test and Validate**: Click **Test**. For JSON format, confirm `result.response` matches the schema. Optionally select a previous playbook run from the drop-down to test with historical data. Review results, check token usage, verify tool execution, and refine your prompt as needed. ## How Hero AI Native Actions Work Hero AI native actions orchestrate intelligent security operations through an iterative reasoning process. Understanding how they work helps you design more effective prompts and leverage their full capabilities. ### Core Components Each Hero AI native action consists of three main components: 1. **Prompt and Instructions**: What you want Hero AI to accomplish - Your custom prompt defines the task or question - Field replacements inject dynamic data from your playbook 2. **The AI Model**: The intelligence powering the action - Uses **Claude** and other models on **Amazon Bedrock** - **Use Default Model** when no model is selected — **Claude Haiku 4.5** on Swimlane-managed routing. See [Hero AI Models](docId\:C1LdFGRmok-7Z2Nei_28b). - Optionally select a specific model in **Model Selection** on the **Prompt** tab to override the default for that action - Interprets your prompt and available context - Generates actions, decisions, and responses based on patterns and real-world data - Reasons about when and how to use configured tools 3. **The Tool Toolbox**: A set of components Hero AI uses to execute tasks - All components in your tenant are available as tools - Hero AI analyzes your prompt and determines which tools to call - Tools execute automatically when Hero AI determines they are needed - Tool outputs are incorporated into the context for generating the final response ### Execution Flow Hero AI native actions execute through multiple **turns**—complete exchanges between the system and the LLM. Each turn includes sending a prompt and receiving a response. Hero AI engages in multiple turns to accomplish complex tasks requiring tool execution and iterative reasoning. **High-Level Process:** 1. **Job Creation and Validation**: The playbook engine creates a Hero AI job and validates inputs (prompt, model, maxOutputTokens, tools, feature flags) 2. **Tool Preparation**: If tools are configured, the system retrieves tool definitions for all selected components 3. **Reasoning and Tool Execution**: Hero AI analyzes your prompt, determines which tools to call, executes them, and incorporates outputs into context 4. **Response Generation**: Hero AI generates a final response based on your prompt, tool outputs, and playbook context 5. **Output Creation**: The system creates action outputs including generated text, token usage, request ID, and finish reason Hero AI breaks down complex tasks into deliberate steps: analyzing available data, weighing options, determining actions, and evaluating results to ensure decisions build on context and drive toward your goal. ### Execution Considerations - **Autonomous Tool Selection**: Hero AI analyzes your prompt and autonomously decides which tools to call and when. You configure available tools, but Hero AI determines the execution plan based on reasoning about what is needed to accomplish your goal. - **Contextual Reasoning**: Hero AI considers available context, tool capabilities, and your prompt when making decisions, similar to how an analyst would approach a problem - **Token Limits**: Responses are truncated if they exceed the `maxOutputTokens` limit. Monitor `result.finishReason` to detect truncation. - **Error Handling**: If execution fails, error information is available in the `error` output field. Hero AI native actions do not fail if underlying tool calls fail—Hero AI continues processing and incorporates tool failure information into its reasoning and response. - **Transparency**: Every action, tool call, and decision is logged, providing full audit trails for review and compliance - **Tool Execution**: Tools are executed via an MCP server that calls the Turbine engine. On-premises deployments run within your cluster, while cloud deployments run within the cloud infrastructure. ## Testing and Validation Testing your Hero AI native action before deploying it to production is crucial for ensuring reliable results. When **Output Format** is **JSON**: - Confirm **Test** results populate `result.response` according to your schema. - If parsing fails to produce structured data, the run can still succeed with free-text content preserved in platform logs — refine the schema and prompt, then retest. - Save the playbook after you are satisfied with the schema so production runs use the persisted definition. ### Testing in the Action Dialog The Hero AI action dialog provides built-in testing capabilities for testing your configuration before deploying to production. These testing features are only available when testing from within the action dialog. 1. **Configure Your Action**: Enter your prompt, optionally select a **Model**, set `maxOutputTokens` if needed, configure tools, and add playbook properties for dynamic data. 2. **Select Test Data** (Optional): Use the **"From previous run"** drop-down to select a previous playbook run (shows up to 20 recent runs with timestamps). If no run is selected, the test uses default/empty data. 3. **Run the Test**: Click the **Test** button. The test status indicator shows "testing" while processing, then "Loaded" when complete or "Error" if it fails. 4. **Review Test Results**: Results appear in the **Result** section below the prompt input, showing: - `result.generatedText`: The AI-generated response - `result.requestId`: Unique request identifier - `result.promptTokens` and `result.responseTokens`: Token usage across all turns - `result.finishReason`: How the response completed (`"Stop"` for natural completion—the happy path, `"length"` if truncated) - `result.turns`: Array containing information about each turn in the execution, including model used, token usage per turn, and tool execution details - `result.configuredTools`: Array showing which tools were configured when the action executed (for historical reference) 5. **Validate Results**: Check response quality, token usage, tool execution (if tools configured), and finish reason. If `finishReason` is `"length"`, increase `maxOutputTokens`. Use the **Copy Result** button to copy the result JSON. **Testing Tips**: Test with multiple playbook runs to validate different data scenarios. Start with simple prompts and gradually add complexity. Test edge cases (empty fields, null values) to ensure robust behavior. ### Validating Responses in Production After deploying your playbook, monitor execution through playbook run logs and details. Validate outputs using conditional actions to check that `result.generatedText` contains expected content and `result.finishReason` indicates successful completion (`"Stop"` for natural completion). Add error handling to check for the `error` field in outputs and implement fallback logic if Hero AI fails. Track execution time and token usage to optimize prompts and `maxOutputTokens` based on actual usage. ## Use Cases and Examples ### Use Case 1: Security Alert Analysis **Scenario**: Automatically analyze security alerts and provide structured summaries. **Solution**: Use Hero AI native action to analyze alerts and extract key information: **Alert Analysis** - **Prompt**: "Analyze this security alert and identify all observables (IPs, domains, file hashes, user accounts). Provide a structured summary with threat assessment." - **Tools**: Threat intelligence lookup components, user context components **Result**: Fast alert analysis with structured summaries that help analysts quickly understand and prioritize alerts. ### Use Case 2: Phishing Email Triage **Scenario**: Automatically analyze reported phishing emails and communicate with users. **Solution**: Use Hero AI native actions to automate analysis and communication: **Email Analysis** - **Prompt**: "Analyze this reported phishing email. Identify phishing indicators, assess threat level, and determine if user communication is needed." - **Tools**: URL analysis component, attachment scanning component, email reputation component **User Communication** (if needed) - **Prompt**: "Generate a user-friendly message explaining the threat assessment for this email. Include what to do if they clicked links or opened attachments." **Result**: Faster initial assessment, automated user communication, and better identification of sophisticated phishing attempts. ### Use Case 3: Threat Intelligence Correlation **Scenario**: Synthesize multiple threat intelligence sources into actionable intelligence. **Solution**: Use Hero AI native action to analyze and correlate TI results: **TI Correlation** - **Prompt**: "Analyze threat intelligence results from multiple providers for these observables: . Correlate findings, identify patterns, resolve conflicts, and provide a consolidated threat assessment with confidence scores." - **Tools**: Multiple TI provider components, historical TI component **Result**: Synthesized intelligence from multiple sources with comprehensive threat reports that save analyst time. ## Best Practices ### Prompt Design 1. **Express Intent, Not Implementation**: Write prompts that describe what you want to accomplish, not how to accomplish it. Let Hero AI reason about the best approach. - ✅ Good: "Analyze this alert and determine if it requires investigation" - ❌ Less effective: "Call TI tool, then check user history, then compare results" 2. **Provide Context**: Include relevant context in your prompt using field replacements. The more context Hero AI has, the better its reasoning. - Include alert details, user information, system state, and similar context - Reference related cases or historical data when relevant 3. **Be Specific About Output Format**: If you need structured output, specify the format in your prompt. - Example: "Provide analysis in this format: Verdict (True Positive/False Positive), Confidence Level, Key Indicators, Recommended Actions" ### Model Selection 4. **Match Model to Task**: Use **Use Default Model** for most playbook automation. Select **Sonnet 4.5**, **Sonnet 4.6**, **Opus 4.5**, or **Opus 4.6** when the prompt requires longer or more complex reasoning; use **Haiku 4.5** or similar fast tiers for high-volume, structured tasks. Confirm regional availability in [Hero AI Models](docId\:C1LdFGRmok-7Z2Nei_28b). ### Tool Configuration 5. **Tool Selection**: There are no hard limits to how many tools can be configured for each native action, but configure only tools necessary for your use case. More tools lead to decreased accuracy and increased response time. - Start with 2-3 essential tools - Add more only if they provide distinct value 6. **Tool Component Design**: When creating components to use as tools: - **Clear Descriptions** (Required): Write descriptions that clearly explain what the tool does and when to use it. Tools without descriptions may not be used effectively by Hero AI. - **Well-Defined Schemas**: Ensure clear input/output schemas so Hero AI understands what data to provide and what to expect - **Error Handling**: Implement robust error handling so tools fail gracefully ### Workflow Design 7. **Multi-Agent Workflows**: When building complex workflows, consider breaking tasks into multiple Hero AI actions, each with a specific role: - Enrichment actions gather and correlate data - Analysis actions reason about findings - Decisioning actions determine next steps - Communication actions handle user interaction 8. **Prevent Infinite Loops**: Design prompts and tool configurations to avoid scenarios where Hero AI might call tools repeatedly without progress. Ensure tool components have clear termination conditions. ## Troubleshooting ### Tools Not Appearing in Selection Dialog **Issue**: Components do not appear in the tool selection dialog. **Solutions**: - Ensure the component is saved and not deleted (deleted components are not available as tools) - Check that you have permissions to view the component - All components and AI agents in your tenant should appear in the **Tools** tab ### Hero AI Not Using Configured Tools **Issue**: Hero AI does not call tools even though they are configured. **Solutions**: - Review tool component descriptions - ensure they clearly indicate when to use the tool - Check that your prompt actually requires the functionality provided by the tools - Verify tool components are working correctly when called directly - Consider refining your prompt to be more explicit about needing tool data ### Component Failure Handling **Issue**: Tool components fail during Hero AI execution. **Solutions**: - Review component execution logs to understand failure reasons - Ensure tool components have proper error handling - Verify tool components are working correctly when called directly - Check that tool components have appropriate timeouts configured - Review component dependencies and ensure they are available ## Observability and Monitoring ### Execution Monitoring Hero AI native actions provide observability through: 1. **Execution Logs**: All Hero AI actions are logged with request IDs, token usage (prompt tokens and response tokens), execution time, tool calls made during execution, and finish reasons 2. **Grafana Dashboards**: LLM calls are logged and available in Grafana dashboards for monitoring token usage trends, execution times, success/failure rates, and tool usage patterns 3. **Playbook Run Details**: Review playbook run details to see Hero AI action execution status, outputs generated, errors encountered, tool execution results, and turn-by-turn execution details 4. **Operational Health Page**: The Operational Health page provides additional visibility: - **New Trigger Type**: A new "Hero AI native action" trigger type filter allows you to view component runs that are part of Hero AI native actions - **Component Run Filtering**: Filter to see just the component runs that are part of Hero AI native action executions - **Sensitive Data Handling**: If components have sensitive inputs marked (via "Mark sensitive" in data inputs configuration), those values are redacted in the UI for security ### Monitoring Best Practices Monitor token consumption over time, track `result.finishReason` to identify truncated responses, analyze which tools Hero AI calls most frequently, track error rates, and monitor execution times to optimize performance and costs.