Run AI Agent Tool

Introduction

The Run AI Agent tool allows you to invoke another existing AI agent from within a current agent flow. This enables modular and reusable design, where complex tasks can be broken down into smaller, dedicated agents that can be triggered as needed.

Get started

How to use it

To use the Run AI Agent Element, add the Run AI Agent tool:

1. Locate the Run AI Agent element under the Tools section of the palette.
2. Drag and drop the element into the Drop a tool here section.
   

Configure Agent Properties

To properly integrate and configure the Run AI Agent, set the following fields:

• AI Agent ID: The unique identifier of the existing AI agent you want to call. This should match the ID of a registered agent in your application. Select from the dropdown, which lists all agents saved in the current app.
• Function Name: A unique name to identify this tool function within the current agent. For example, run_billing_agent. The default is run_agent.
• Context Propagation: Whether the parent's conversation so far is shared with the sub-agent. Enter None (default) to give the sub-agent only the inputs the parent fills in, or Pass conversation history to also share the parent's recent messages so the sub-agent can see what was already discussed.
• Max Messages to Pass: How many of the parent's recent messages to share. Appears only when Context Propagation is Pass conversation history. Enter a whole number. The most recent messages up to this count are passed; older ones are dropped. The default is 10.
• Trace Visibility Level: How much of the sub-agent's run the parent receives back as the tool result. Final Output Only (default) returns just the sub-agent's answer, Summary (output + tool names) returns the answer plus the names of the tools the sub-agent used, and Full Trace (all steps as JSON) returns a JSON object with the answer and the sub-agent's complete step-by-step trace.

Tips and gotchas

• Declare inputs on the sub-agent first. The parent LLM learns what to pass to the sub-agent from the sub-agent's own declared input variables. If the sub-agent has no declared inputs, the tool generates a function with no parameters, and the parent cannot pass any values. Define the inputs on the sub-agent before wiring it up here.
• Use a descriptive Function Name. The parent LLM decides which sub-agent to call based on its function name and description. A name like run_billing_agent is far clearer than the default run_agent, especially when multiple sub-agents are present.
• Sub-agents run in the same app context. The sub-agent shares the same workflow assignment and run lineage as the parent. It has access to the same app data.
• Each sub-agent is a separate tool instance. There is no limit on the number of Run Agent tools you can add to one parent agent, but each adds a function definition the LLM must process. Keep the total number of tools manageable.
• Pass conversation history only when the sub-agent needs the back-story. With Context Propagation set to None, the sub-agent starts fresh and sees only the inputs the parent fills in. Switch to Pass conversation history when the sub-agent's answer depends on what the user and parent already discussed. Keep Max Messages to Pass modest every shared message is added to the sub-agent's context and counts toward its token budget. The parent's own system messages are never shared; the sub-agent always uses its own persona and prompts.
• Raise Trace Visibility Level when you are debugging, not in production. Final Output Only keeps the parent's context clean and is the right default. Summary is useful when the parent needs to know which tools the sub-agent ran. Full Trace returns the sub-agent's entire step-by-step run as JSON, valuable while diagnosing a multi-agent flow, but it can be large, so avoid leaving it on for everyday runs.