Skip to main content

Configuring the Zeta Alpha Orchestrator agent

This tutorial explains the Zeta Alpha Orchestrator agent and how you can configure it for your tenant or usecase based on your needs.

Prerequisites​

  • Admin access to the Zeta Alpha platform UI.

Overview​

The orchestrator is a built-in Zeta Alpha agent that can be configured in its bot_configuration with specific tools and instructions in order to be customized for a specific usecase. You can then make the agent available to the tenant, as explained in the previous section of Configuring Agents. The bot_configuration parameters of the orchestrator agent are shown below:

  • tools: a list of objects defining the tools that are available to the orchestrator
  • instructions: custom instructions placed in the system prompt, used to steer the behavior of the orchestrator
  • platform_description: a description related to the specific tenant on which the agent operates on.

As an example, below you can see the bot_configuration of an orchestrator instance that is configured to work with the documents indexed to Zeta Alpha to which the user has access to, and is prompted to answer in a specific format.

{
  "bot_configuration": {
    "platform_description": "Tenant Foo is a market leader in software services",
    "instructions": "Answer with a brief and concise summary at the beginning, followed by a section with more details related to your answer",
    "tools": [
      {
        "enabled": true,
        "description": "Search in the whole internal index for relevant context.",
        "display_name": "Internal search",
        "agent_tool_name": "search_context_in_internal_index"
      }
    ]
  }
}

Instructions​

Use the bot_configuration.instructions field to customize the behavior of the orchestrator agent with specific instructions. This text is used to enhance the built-in system prompt of the Zeta Alpha orchestrator with custom instructions.

Tools​

You can enable one tool (e.g. search_context_in_internal_index) by adding a corresponding entry inside the bot_configuration.tools, e.g.

{
    "enabled": true,
    "agent_tool_name": "search_context_in_internal_index"
}

You can also add the fields description, display_name in a tool configuration which overrides the built-in description of the tool. An example is the following:

{
  "enabled": true,
  "description": "Read or search inside the provided document. Always pass the document id to this tool call.",
  "display_name": "Search in the documents",
  "agent_tool_name": "search_context_in_internal_index"
}

The following tools can be enabled based on your needs.

Search tools​

  1. search_context_in_internal_index: Search in the internal index for relevant context.

  2. search_context_in_private_documents: Search in the user’s private documents for relevant context.

  3. search_context_from_image_in_internal_index: Search for documents related to an image by providing an image ID and a query.

  4. search_web: Search the web for relevant context.

  5. search_academic: Search public academic literature and papers.

Document access​

To use these tools, you should also add the following parameter inside bot_configuration:

"collection_tools_config": {
  "fe_base_url": "https://{tenant}-search.{domain url}"
}

  1. locate_document: Locate a document when the user mentions a title, filename, or URL (supports fuzzy matching).

  2. read_document: Read the full content of a document using its document ID.

Document organization tools​

To use these tools, you should also add the following parameter inside bot_configuration:

"organizing_tools_config": {
  "fe_base_url": "https://{tenant}-search.{domain url}"
}

  1. list_user_tags: List all tags the user has access to, including metadata.

  2. list_documents_in_tag: List documents inside a specific tag with pagination support.

Data Analysis tools (Tabular files – CSV/Excel)​

To use these tools, verify that a dataframe_tabular_agent is already configured in the tenant settings under the chat_bot_setups.

  1. load_dataframe: Load a CSV or Excel document from a document ID into a named DataFrame.

  2. get_dataframe_schema: Get column names, data types, and sample values from a DataFrame.

  3. preview_dataframe: Preview sample rows from a DataFrame.

  4. read_dataframe: Read rows from a DataFrame with extended options.

  5. count_dataframe_rows: Count the number of rows in a DataFrame.

  6. get_column_values: Retrieve all or distinct values from a column.

  7. get_column_statistics: Get statistics such as mean, median, standard deviation, min, max, and count for numeric columns.

  8. get_missing_value_counts: Count missing values (NaN, None, NaT) in specified columns.

  9. filter_dataframe_rows: Extract rows matching specific conditions.

  10. sort_dataframe_rows: Sort DataFrame rows by column and order.

  11. aggregate_column: Aggregate a numeric column, optionally grouped by another column.

  12. merge_dataframes: Merge two DataFrames using SQL-style joins (inner, left, right, outer).

  13. concatenate_dataframes: Concatenate multiple DataFrames by rows or columns.

Deep Research​

  1. handoff_to_research_agent: Conduct in-depth research across multiple sources and generate a detailed research report. This should be used along with the bot_configuration.confirm_research_request_with_user parameter set to true, in order to allow the agent to propose a plan for the research report to the user before triggering it.