Skip to main content
Version: 1.0

Build

Overview​

This guide covers how to create AI agents in aiXplain Studio. You'll learn to build:

  • Single agents - Agents that use tools and models to accomplish tasks
  • Team agents (multi-agent systems) - Orchestrated groups of specialized agents working together

Accessing the Build Experience​

Navigate to the Build section by either:

  • Clicking Build in Studio
  • Going directly to studio.aixplain.com/build

Build Directory​

When you open Build, you'll see the Build Directory with three sections:

Templates​

Pre-built example agents demonstrating different capabilities and use cases. Click Use on any template to create it as your own agent.

Drafts​

Agents you've started configuring but haven't saved/deployed yet.

Agents​

Your created and deployed agents (both single agents and team agents).

Note: If you haven't created any agents yet, you'll only see the Templates section.

Starting a New Agent​

You have three options to begin:

Option 1: Use a Template​

  1. Click Use next to any template
  2. Review the template configuration
  3. Click Create to make it your own

Option 2: Start from an Existing Agent​

  1. Click Use on any of your existing agents or drafts
  2. Modify the configuration as needed
  3. Click Create to deploy as a new agent

Option 3: Create from Scratch​

Click the Create new agent button to start with a blank configuration.

The Agent Builder Canvas​

When you create or edit an agent, you enter the Agent Builder Canvas with three tabs:

  1. Schema - Configure your agent
  2. Validation - Test and monitor execution
  3. Publish (Coming soon)

Building a Single Agent​

Single agents use tools and models to accomplish tasks. They cannot contain other agents as components.

Step 1: Configure Basic Settings (Schema Tab)​

Click the configuration icon next to "New Agent" at the top to access settings.

Required Fields​

Name (Required)

  • Must be unique across your agents
  • Used to identify your agent

Description (Required)

  • 1-2 lines recommended
  • Describes the agent's role and main purpose
  • Visible to: the agent itself, anyone you share with, and other agents that use this agent
  • Critical: Used by other agents to understand how to use this agent

Instructions (Optional)

  • Describe your agent's behavior in natural language
  • Include:
    • Do's and don'ts
    • Step-by-step procedures
    • Desired output format and style
  • Can be as detailed as needed
  • Primary field for iteration - You'll refine this as you improve your agent

Output Format (Optional)

  • Text (default)
  • Markdown
  • JSON

Language Model (Required, pre-selected)

  • The LLM that powers your agent
  • One is selected by default
  • Can switch to any available LLM

Maximum Iterations (Optional, has default)

  • Limits how many loops the agent can execute
  • Prevents excessive credit consumption and long runtimes
  • Has a sensible default value

Maximum Tokens (Optional, has default)

  • Controls token generation limit
  • Upper limit depends on selected LLM (enforced by system)
  • Has a sensible default value
  • Note: Restricts tokens for the final response

Generate Button (Coming soon)

  • Will auto-generate description and instructions using AI

Step 2: Add Tools and Models​

Extend your agent's capabilities by adding tools and models. Click the + button to see options.

Adding a Tool​

  1. Click Add Tool
  2. Browse tools in the marketplace view
  3. Click Use this asset on any tool card
  4. Select which actions to include:
    • Enable all - Includes all actions (not recommended)
    • Select specific actions - Choose only what you need (recommended)
    • No selection - First 20 actions included by default

Best practices:

  • Add only necessary tools
  • Select specific actions, not all
  • Stay within 10-15 tools for optimal performance
  • Too many tools hinder agent performance

Adding a Model as a Tool​

  1. Click Add Model
  2. Browse all model assets (LLMs, text-to-speech, sentiment, vision models, etc.)
  3. Click Use this asset

Models function as specialized tools within your agent.

Adding Integrations Directly​

  1. Click Add Integration
  2. Browse integration assets
  3. Click Use this asset
  4. Click Connect on the added integration
  5. Provide required information (API keys, configurations, etc.)
  6. Select which actions to include

This creates a private tool from the integration that's immediately available to your agent.

Editing Tool Descriptions​

You can modify any attached tool's description:

  • Click edit on the tool
  • Update the description
  • Save changes

Important: This only affects the description for this specific agent. The original tool asset remains unchanged.

Managing Tools​

  • Remove tools after adding them
  • Add multiple tools
  • Reorder tools as needed

Step 3: Deploy Your Agent​

Once you've configured your agent's basic settings and added tools/models, click Create to deploy.

Important: Clicking Create immediately deploys your agent as a private asset.

Step 4: Test Your Agent (Validation Tab)​

After creating your agent, test it to ensure it works as intended.

Starting a Test​

Two ways to begin:

  1. From Schema tab: Click the blue Chat icon (automatically switches to Validation)
  2. From Validation tab: Click Start validation and enter your query

Chat Interface Features​

Enter your query: Type your question or prompt in the chat input.

Upload files: Click the + button to upload:

  • Audio files
  • Video files
  • Image files
  • Text files

Files accompany your text input. Ensure your agent has tools that can process the file types you upload.

Recommended tool for file processing: DuckLink converts images and text files into text the agent can use.

Conversation memory: Agents maintain conversation history, allowing natural follow-up questions.

Understanding Validation Display​

When you send your query, the agent executes and displays real-time progress in the Validation tab.

For each component the agent uses, you'll see:

  • Component name and description
  • Input - Data sent to the component
  • Output - Data received from the component
  • Thought - Reasoning process (primarily for LLMs)
  • Details:
    • Number of API calls
    • Credits consumed
    • Duration
    • Start time
    • End time

Tracking behavior: Click any component to examine its execution details and trace the agent's decision-making.

Final response: When execution completes, the final response appears in both the Validation tab and the Chat interface.

Step 5: Update Your Agent​

To modify a deployed agent:

  1. Go to the Schema tab
  2. Make your changes:
    • Add/remove tools
    • Modify configuration settings (name, description, instructions, LLM, etc.)
    • Edit tool descriptions
  3. Click Update to redeploy with the new configuration

The agent redeploys immediately with your changes.

Viewing Your Agent as an Asset​

After creation, your agent appears in the Browse experience:

  1. Navigate to Browse > Agents
  2. Your agent is listed with Privacy set to Private by default

From Browse, you can:

  • View specifications
  • Use the API Integration tab for programmatic access
  • Chat with it via Tryout
  • Edit metadata (name and description)
  • Transfer to another team
  • Delete it

Building a Team Agent (Multi-Agent System)​

Team agents orchestrate multiple specialized agents working together to accomplish complex tasks.

When to Use Team Agents​

  • Use single agent with tools: For tasks requiring API calls, models, or integrations
  • Use team agent: For complex workflows requiring specialized sub-agents with different capabilities

Critical constraint: You cannot mix tools and agents:

  • Adding tools → Creates a single agent
  • Adding agents → Creates a team agent

Creating a Team Agent​

Step 1: Start Fresh​

If you've already added tools and want to create a team instead:

  1. Click Start over to clear configuration
  2. Set up basic settings (name, description, instructions, etc.)

Step 2: Configure Basic Settings​

Configure the same basic settings as a single agent:

  • Name (required)
  • Description (required)
  • Instructions (optional but recommended)
  • Output format
  • Language model
  • Maximum iterations
  • Maximum tokens

Step 3: Add Sub-Agents​

Click the + button and select Add Agent.

You have two options:

Option 1: Pick an Existing Agent

  1. Click Pick an agent
  2. Browse available agents (public or your private agents)
  3. Click Use this asset to add to your team

Option 2: Create a New Sub-Agent

  1. Click Create team agent
  2. Configure the new agent from scratch (name, description, instructions, etc.)
  3. The agent is created and automatically added to your team

Note: Every sub-agent you create becomes its own agent asset with Private visibility.

You can add as many sub-agents as needed, though keeping the number manageable improves maintainability.

Understanding Team Agent Architecture: Micro-Agents​

When you create a team agent, four micro-agents automatically orchestrate your sub-agents. These appear as additional parameters in the Schema tab:

1. Planner​

Purpose: Analyzes the user's request and creates an execution plan

The Planner determines what steps are needed to accomplish the goal.

2. Orchestrator​

Purpose: Executes the plan by calling the appropriate sub-agents in sequence

The Orchestrator receives the Planner's output and routes work to sub-agents.

3. Inspector (Optional)​

Purpose: Validates outputs against policies and criteria

The Inspector provides governance over your team's behavior.

Enabling and configuring the Inspector:

  1. Click Enable in the Inspector section

  2. Inspector Name
    Example: "Hate Speech Filter"

  3. Description
    Define what comprises a violation
    Example: "Filter content containing hate speech, including [specific criteria]"

  4. Target - Choose where to check:

    • Steps - Check every sub-agent's output
    • Input - Check only initial team agent input
    • Output - Check only final team agent output

  5. Policy - Set violation response:

    • Continue - Log the problem but proceed
    • Rerun - Provide feedback and regenerate with the sub-agent
    • Abort - Stop execution immediately

You can configure multiple Inspectors with different criteria and policies.

4. Responder​

Purpose: Formats the final output according to your specifications

The Responder is present in both single agents and team agents.

Formatting priority:

  1. Output format parameter (Text, Markdown, JSON) - highest priority
  2. Instructions from agent configuration

Managing Sub-Agents​

Sub-Agents as Assets​

Every sub-agent automatically becomes its own agent asset:

  • Appears in Browse under Agents
  • Set to Private visibility
  • Can be used in other teams
  • Can be used independently via chat or API

Distinguishing Team Agents from Single Agents​

When viewing agents in Browse:

Single Agent specifications show:

  • "Tools" section listing attached tools

Team Agent specifications show:

  • "Sub-agents" section listing member agents

Critical: Shared Sub-Agent Configuration​

Important consideration:

When you modify a sub-agent's configuration (name, description, instructions, or any setting) within a team agent:

  • Changes are permanent
  • They affect the sub-agent asset itself
  • They impact all teams using this sub-agent

Example:

  • Sub-agent "Data Analyzer" is used in Team A and Team B
  • You edit "Data Analyzer" while in Team A
  • Changes immediately affect Team B's usage

Upcoming feature: Duplication will allow you to copy sub-agents before editing, preventing unintended cross-team impacts.

Testing Team Agents (Validation Tab)​

Team agents are tested the same way as single agents:

  1. Click Chat icon or go to Validation tab
  2. Enter your query (with optional file uploads)
  3. Monitor real-time execution

Validation Display for Team Agents​

You'll see execution of:

  • Planner - Creating the execution plan
  • Orchestrator - Routing to sub-agents
  • Each sub-agent - Inputs, outputs, and internal execution
  • Inspector - Checks and any violations detected
  • Responder - Formatting the final output

This provides full visibility into your multi-agent system's decision-making.

Updating Team Agents​

To modify a deployed team agent:

  1. Navigate to Schema tab
  2. Make changes:
    • Add/remove sub-agents
    • Modify micro-agent configurations (Inspector settings, etc.)
    • Adjust main agent settings
  3. Click Update to redeploy

Remember: Configuration changes to sub-agents affect the underlying asset and all teams using it.

Best Practices​

For Single Agents​

  • Add only necessary tools (stay within 10-15)
  • Select specific tool actions, not all available actions
  • Iterate on instructions based on validation results
  • Test with various inputs to ensure reliability

For Team Agents​

  • Keep team size manageable
  • Design sub-agents with specific, well-defined purposes
  • Use Inspectors strategically where they add value
  • Test iteratively, starting with simple queries
  • Monitor validation traces to understand orchestration decisions