Managing an AI agent using Orchestration CLI

You can create an AI agent of basic agent type using Orchestration CLI. After you create an AI agent, you can run it as task or communicate with the agent using the chatbot function to get the required results.

Overview

You can integrate workflows and specific AI models (Large Language Model) to create an AI agent, that acts as a hub for information which can be accessed on demand. The AI Agent facilitates access to organised information, permitting AI models to automate tasks or provide rapid responses from the information centre. You must use the UI to create an AI agent of agent types external MCP and agentic AI builder.

Prerequisites

You must have completed the following:
  • Created required workflows.
  • Obtained ADD access.
  • Obtained USE access on the AI agent.
  • Obtained USE access on the workflows that you want to add in the AI agent.
  • Configured the required AI models (LLM) in your HCL Universal Orchestrator environment. For more information, see Managing agent types in the AI agent.

Syntax and command line options

You can run the command as follows to create an AI agent: 
Ocli model new aiagent
After running the command, complete the following template to create an AI agent: 
---
kind: AIAgent
def:
  folder: folder_name
  name: name
  description:
 *agentType: [basic | externalMCP| agentbuilder]
 *displayName:
  chatbot: [true | false]
  role: 
  model: 
  temperature: [0 to 2.0]  
  instructions:
  workflows:
    workflow: workflow_x
    workflow: workflow_y
*The attribute is not displayed in the default template and must be added manually.
The mandatory attributes to create the agent is as follows:
folder

Specify a folder to save the AI Agent definition. The default value is the root folder (/). The name must start with a letter, and can contain alphanumeric characters, dashes, and underscores. The name of the folder cannot contain spaces.

You must include a forward slash (/) before the folder name if you want to define an absolute path, while it is not required for relative paths.
name

Specify a name for the AI Agent. The name must start with a letter, and can contain alphanumeric characters, dashes, and underscores. The name cannot contain spaces.

The following attributes are added automatically, if you do not specify any values:
agentType
You can specify the AI model type that you want to utilize to assist the operations managed by the AI agent. The default value is basic. You can add any one of the following value:
  • basic
    The AI models (LLM) are configured directly with the agent. If you add basic as the value, then you must add the following key-value pair.
    model
    You can add any one of the AI models configured in your environment (the AI models configured in the values.yaml file). The default value is gemini-2.0-flash.
    Example: gpt-4, amazon.nova-micro-v1:0,anthropic.claude-3-haiku-20240307-, gemini-2.0-flash, gemini-2.5-flash.
    You can configure any AI models provided by the foundational model platforms or AI/Machine learning cloud platforms. You must have configured those AI models in your environment by configuring the values.yaml file. For more information, see Managing agent types in the AI agent.
  • externalMCP
    Add this option, if you want to integrate the AI agent with external MCP platforms. When you create the AI agent a unique URL with the agent ID (MCP server URL) is auto generated at the back end. You can use this URL to connect the AI agent with any external MCP server. Access the UI to view the MCP server URL of the associated AI agent. You can then communicate with the MCP server using its access points and it provides responses powered by the integrated AI models. For more information, see Course of action if the agent type is External MCP.
  • agentbuilder
    The advanced and customized AI agents that utilize multiple AI models. When you create the AI agent, a unique URL with the agent ID (MCP server URL) is auto generated at the back end. Log in to the UI to view the MCP server URL of the associated AI agent. Use this URL to connect the AI agent with the Agentic AI Builder. For more information, see UnO Agentic AI Builder. If you add agenticbuilder as the value, then you must add the following key-value pair.
    agenticAiBuilderAgentName
    Add the name of the agent package. You must have updated the values.yaml file to set the value of the attribute enableAgenticAIBuilder to true.
The optional attributes to customize the agent is as follows:
description
Provide a description for the AI Agent. You can add information about the workflows that are added in the agent, details like what the workflows do and output that it produces. This detail helps the Agent type to manage the AI agent more efficiently and effectively.
displayName
Specify a name to identify the AI Agent in the AI Agents section in the Graphical Designer page. You must add this attribute, only if you want to create an AI agent with a chatbot interface. The name must start with a letter or a number, and can contain alphanumeric characters, dashes, and underscores. The name cannot contain spaces. If no details are added, then the name specified for the name is used to identify the AI Agent.
chatbot

if you want to interact with the AI Agent in a chatbot interface, set the option to true. Enabling this option, creates a chatbot interface for the AI agent in the Agent Apps section in the UI. If this option is not set, you must run tasks to interact with the AI Agent.

workflows
Add all the required workflows to the AI Agent. You can add multiple workflows in an AI agent.
Specific attributes for basic agent type
The following are specific attributes to customize the basic agent type.
role

You can specify the role of the agent in free-form text.

temperature

It controls the randomness and creativity of the output or generated text provided by the AI agent. You can select any value between 0 and 2.0. A value close to 0 gives more generic and common phrasing. A value close to 2.0 gives a more unique phrasing.

instructions

You can provide instructions to the AI Agent in free-form text. The content you add here plays a vital role in the performance of AI Agent. Based on the instructions provided here, the agent manages the workflows included in the AI Agent to provide the output. You can specify all the operations and tasks the agent must perform.

guardrails

You can specify all the operations the AI agent should avoid. Specify all the restrictions and limitations you want to put on managing the data transfer.

topP

Top-p, or nucleus sampling, is an the attribute that controls the diversity of the generated text. It selects the smallest set of most probable next words whose cumulative probability exceeds a specified threshold (between 0 and 1). The model then samples the next word only from this "nucleus" set. A higher value leads to more diverse and creative outputs, while a lower results in more focused and predictable text.

You have successfully created an AI agent. You can interact with the AI agent either from the AI Agents section in the UI or you can create tasks to run the AI agent.

Examples

  1. To create an AI agent as follows with an external source that can retrieve policy details by running specific workflows, define it as follows:
    ---
kind: AIAgent
def:
  folder: /policy_insurance
  name: get_policy_details
  description: 
  agentType: externalMCP
  displayName: policy_retriever
  chatbot: true
  workflows:
     workflow: /get_policy_name
     workflow: /get_policy_scheme
  2. To create an AI agent with the Agentic AI Builder that can retrieve policy details by running specific workflows, define it as follows: 
    ---
kind: AIAgent
def:
  folder: /policy_insurance
  name: get_policy_details
  description: 
  agentType: agentbuilder
  agenticAiBuilderAgentName: policy_agent
  displayName: policy_retriever
  chatbot: true
  workflows:
     workflow: /get_policy_name
     workflow: /get_policy_scheme