ZBrain

Define crew structure

This step sets up the layout of your Agent Crew. You can create agents from scratch or import them from your existing library. Each agent can be connected to others to establish a hierarchy, where supervisor agents manage task flow and sub-agents handle specific functions.

Importing a crew configuration (JSON)

  • Follow these steps to import a crew configuration into your project:

    1. Click the Settings (gear) icon.

    2. Select ‘Import Crew’ from the menu.

    3. Choose the desired .json file from your local directory.

    4. If a crew with the same name already exists, you may be prompted to confirm before proceeding.

    5. Once confirmed, the crew configuration is imported and added to your project.

How to create the agent crew structure

To build the crew structure, you can either create new agents or select existing ones from your ‘Agent Library’. These agents are then arranged on a visual canvas, where you define the execution flow and task delegation by connecting them.

Create a new agent

  1. When you are directed to the ‘Define Crew Structure’ step, a default root agent (main agent) is already present on the canvas. This is the starting node of your Agent Crew. You can rename or reconfigure this agent as needed to match your use case.

  2. To create sub/child agents, click on ‘+Add Agent’ and select ‘Create New’ or ‘Add from library’.

  1. A new, unnamed agent box appears on the canvas. At the same time, a sidebar titled ‘Create New Agent’ appears, displaying the following fields:

    • Agent Name: Enter a name for the agent.

    • Agent Type: Select the agent type from the dropdown. Currently supports ‘Autonomous’ agent type.

    • Description: Describe the purpose of the agent.

    • Instructions: Define the instructions you want the agent to follow using natural language prompts. This could include the role, behavior and interaction style of the agent.

  1. You can enable Human-in-the-Loop (HITL) controls at the agent level by enabling the 'Human in loop' toggle, allowing you to pause workflows at key steps, review outputs, and decide whether to proceed, edit, or re-run tasks.

  • Key actions

    • Pause at predefined steps: Agents stop after completing their task, presenting intermediate results and seeking human input in orange color.

  • Review and approve: Users can approve results to continue downstream execution with the required input.

  • Edit or re-run: Modify inputs or re-run the task before passing outputs to the next agent.

    • Agent-level control: HITL can be toggled on or off per agent within a crew, applied only where validation is critical.

    • Seamless integration: HITL prompts and controls are built directly into agent dashboards and crew structures.

  1. Configure per-agent models in a crew

ZBrain Builder supports per-agent model configuration inside agent crews, so each agent can run on the LLM best suited to its role. This enables finer-grained performance tuning, quality control, and cost optimization versus a single crew-wide model. Follow these steps to assign a specific model to an individual agent within a crew:

  1. Open the crew editor: Agents → Define Crew Structure

  2. Select the agent: Click the agent node/card in the crew canvas/list.

  3. Open the agent side panel: The agent details panel appears on the right.

  4. Choose the model: Go to Model and select the desired LLM from the dropdown.

    • (Optional) Adjust parameters (e.g., temperature, max tokens) if available.

  5. Save changes: Click ‘Save’ to commit the configuration. The selected agent now uses its own model at runtime, overriding any crew-level default.

  1. Under ‘Agent Tools’, click ‘+Add’ to attach tools. A new window will appear where you can either select from ‘Default Tools’ (prebuilt tools available) or create a new one. Tools you’ve previously created will appear in the 'My Tools' section for future use.

  2. ZBrain Builder supports default tools, such as Google search, Knowledge Base search, HTTP and the Deep Research Tool.

You can enhance agent capabilities by attaching a Retrieval Augmented Generation (RAG)-powered knowledge base, enabling the agent to access domain-specific context during execution.

  • Click “Knowledge Base Search” and edit the tool according to your requirements.

    • You can select any previously created knowledge base from the drop-down.

    • Provide an appropriate description of the purpose of using the knowledge base.

  • Click 'Add' to add the tool to your agent structure.

To create a new tool, click the ‘New Tool’ button. This opens a new interface with the following fields:

  1. Name: Enter a name for your tool.

  2. Description: Briefly describe what the tool does.

  3. Inputs: Click ‘+ Add Items’ to define input variables.

  4. Code: Write your custom JavaScript code.

  5. Dependencies(Optional): Specify any external libraries or dependencies. Here you can add external dependencies (e.g., npm packages) directly to an agent’s tool.

    • Click on ‘Add package’ and provide the package name you want to add, and click 'Save'. The latest version of the package will be automatically added to the tool's list of dependencies. This supports automatic version resolution and easy rollback.

  1. Attaching an MCP server

Follow these steps to attach an MCP server to your crew:

  1. Navigate to MCP Servers in the crew editor.

  2. Click + Add a MCP Server.

  3. The MCP Library window will appear, showing any previously connected systems.

  4. Select an existing MCP server (ZBrain or external) to attach it to the crew or agent.

  5. Click Save to complete the connection.

Note: You can attach existing ZBrain MCP servers to agents within a crew to reuse pre-configured capabilities without duplicating setup. ZBrain MCPs can be used alongside external MCPs in the same crew.

  1. To add a ZBrain MCP server -

  • In the interface, click ‘Add MCP’, then click ‘Add ZBrain MCP Server’.

  • After making a selection, a confirmation dialog appears, prompting you to save your crew configuration. Once saved, you are redirected to the ZBrain MCP Settings page.

  • Select the required MCP server from the available list.

  • The MCP server will be added to the crew agent.

The agent can now call tools/endpoints exposed by the selected ZBrain MCP at runtime. The MCP server appears in the agent’s MCP server list and can be used in prompts, flows, and crew runs.

  1. To add a new MCP server, click on the ‘External MCP Servers’ from ‘Add MCP’. You’ll be directed to another window wherein you have to fill in:

    • MCP server name

    • Description

    • MCP server URL

    • Headers (optional key-value pairs in {"key": "value"} format)

Click ‘Save’ to store the MCP server. It will then appear in the MCP library for future selection.

  1. Click ‘Save’ to confirm and close the sidebar. The agent is now part of the crew structure.

Add an agent from the library

  1. Click on ‘Add Agent’ and select ‘Add from Library’.

  2. A sidebar titled ‘Agent Library’ appears.

  3. Browse or search for agents from existing categories, ‘Autonomous’ and ‘ZBrain Flow’.

  1. Select the desired agent.

Define agent hierarchy

  1. Each agent box has circular connectors on its left and right.

  2. Hover over a connector to display a + cursor.

  3. Click and drag from one agent’s connector to another’s to define the task flow. Ensure that you arrange the agent box in the hierarchy you require.

  1. Multiple agents can be connected to the same supervisor, depending on task requirements.

  2. You can view the agent crew type (Supervisor, Autonomous, or ZBrain Flow) directly within the agent interface under the crew structure.

  3. Within the Crew editor, the currently selected node is outlined in blue, while unselected nodes retain a gray border, allowing for rapid visual focus as complex graphs become more intricate.

Exporting a crew configuration (JSON)

You can export agent crew configurations as JSON and import them back when needed—supporting backup, sharing, and restoration across projects and environments.

  1. Open the crew editor: Agents → Define Crew Structure

  2. Click the Settings (gear) icon.

  3. Choose ‘Save Crew’.

  4. Confirm the download location and file name (saved as .json).

  5. A JSON file containing the selected crew configuration is saved locally.

How to test your crew setup

  1. Click on the ‘Test Crew’ button at the top.

  2. A sidebar named ‘Test Crew’ opens with a message box.

  3. Enter a test message to simulate a task or query.

  4. Click send to observe how the crew processes the input.

  1. The system displays the outputs generated by the agents, helping you validate the structure.

Use the ‘Previous’ and ‘Next’ buttons at the top to move between steps in the Agent Crew creation process.

PreviousSet up input sourcesNextAdditional settings

Last updated