Skip to content
LOPS Docs

Agent Operator

Overview

Section titled “Overview”

The Agent operator is the central component for managing interactions with Large Language Models (LLMs). It handles assembling prompts, sending requests (including images and audio), processing responses, managing conversation history, executing tools, and handling callbacks.

Agent Operator

Key Features

Section titled “Key Features”
  • Connect directly to multiple AI providers through LiteLLM integration
  • Send and receive text, images, and audio (with provider support)
  • Control LLM parameters (temperature, max tokens, etc.)
  • Access advanced features like streaming responses
  • Configurable output formats (conversation, table, parameters)
  • Enable dynamic AI tools for parameter control and custom functionality
  • Grab contextual information from other operators
  • Callback system for integrating with other components

Parameters

Section titled “Parameters”

Page: Agent

Section titled “Page: Agent”
Call Agent (Call) op('agent').par.Call Pulse

Pulse this parameter to initiate a call to the language model using the current settings.

Default:
0
Call on in1 Table Change (Onin1) op('agent').par.Onin1 Toggle

When enabled, the Agent will automatically call the LLM whenever the input table changes.

Default:
0
Options:
off, on
Use Streaming (Streaming) op('agent').par.Streaming Toggle

When enabled, responses are delivered in chunks as they are generated.

Default:
1
Options:
off, on
Update Table When Streaming (Streamingupdatetable) op('agent').par.Streamingupdatetable Toggle

When enabled, conversation table is updated as streaming chunks arrive.

Default:
0
Options:
off, on
Current Task (Taskcurrent) op('agent').par.Taskcurrent Str

Displays the current state of the Agent. Read-only parameter updated by the system.

Default:
Idle
Timer (Timer) op('agent').par.Timer Float

Displays timing information for the last LLM call.

Default:
0.06666667014360428
Active (Active) op('agent').par.Active Toggle

Indicates if the Agent is currently processing a request. Read-only parameter.

Default:
0
Options:
off, on
Agent Role Definition / Info Header
System Message DAT (Systemmessagedat) op('agent').par.Systemmessagedat OP

The DAT containing the system message text to send to the LLM. This defines the agent's role/persona.

Default:
/DOC_GENERATOR/NETWORK_VIEWER/agent1/system_message
System Message (Last) (Displaysysmess) op('agent').par.Displaysysmess Str

Displays the last system message that was sent. Read-only parameter.

Default:
be confident and helpful and direct!
Editsysmess (Editsysmess) op('agent').par.Editsysmess Pulse

Pulse to open the system message DAT for editing.

Default:
0
Use System Message (Usesystemmessage) op('agent').par.Usesystemmessage Toggle

When disabled, system messages are not sent to the model (for models that do not support system messages).

Default:
1
Options:
off, on
Spacer Header

Page: Model

Section titled “Page: Model”

Understanding Model Selection

Operators utilizing LLMs (LOPs) offer flexible ways to configure the AI model used:

  • ChatTD Model (Default): By default, LOPs inherit model settings (API Server and Model) from the central ChatTD component. You can configure ChatTD via the "Controls" section in the Operator Create Dialog or its parameter page.
  • Custom Model: Select this option in "Use Model From" to override the ChatTD settings and specify the API Server and AI Model directly within this operator.
  • Controller Model: Choose this to have the LOP inherit its API Server and AI Model parameters from another operator (like a different Agent or any LOP with model parameters) specified in the Controller [ Model ] parameter. This allows centralizing model control.

The Search toggle filters the AI Model dropdown based on keywords entered in Model Search. The Show Model Info toggle (if available) displays detailed information about the selected model directly in the operator's viewer, including cost and token limits.

Available LLM Models + Providers Resources

The following links point to API key pages or documentation for the supported providers. For a complete and up-to-date list, see the LiteLLM provider docs.

Output Settings Header
Max Tokens (Maxtokens) op('agent').par.Maxtokens Int

The maximum number of tokens the model should generate.

Default:
4096
Temperature (Temperature) op('agent').par.Temperature Float

Controls randomness in the response. Lower values are more deterministic.

Default:
0.7
Model Selection Header
Use Model From (Modelselection) op('agent').par.Modelselection Menu

Choose where the model configuration comes from.

Default:
custom_model
Options:
chattd_model, custom_model, controller_model
Controller [ Model ] (Modelcontroller) op('agent').par.Modelcontroller OP

Operator providing model settings when 'Use Model From' is set to controller_model.

Default:
None
Select API Server (Apiserver) op('agent').par.Apiserver StrMenu

Select the LiteLLM provider (API server).

Default:
openrouter
Menu Options:
  • openrouter (openrouter)
  • openai (openai)
  • groq (groq)
  • gemini (gemini)
  • ollama (ollama)
  • lmstudio (lmstudio)
  • custom (custom)
AI Model (Model) op('agent').par.Model StrMenu

Specific model to request. Available options depend on the selected provider.

Default:
gemini-1.5-flash
Menu Options:
  • gemini-1.5-flash (gemini-1.5-flash)
Search (Search) op('agent').par.Search Toggle

Enable dynamic model search based on a pattern.

Default:
off
Options:
off, on
Model Search (Modelsearch) op('agent').par.Modelsearch Str

Pattern to filter models when Search is enabled.

Default:
"" (Empty String)
Show Model Info (Showmodelinfo) op('agent').par.Showmodelinfo Toggle

Displays detailed information about the selected model in the operator's viewer.

Default:
1
Options:
off, on

Page: Tools

Section titled “Page: Tools”
Use Tools (Usetools) op('agent').par.Usetools Toggle

When enabled, the Agent can use tools defined below during its interactions.

Default:
0
Options:
off, on
Custom Parameter Controls Header
Add / Remove Controls (Optool) op('agent').par.Optool Sequence

Sequence parameter that controls groups of parameter control tools.

Default:
0
Select Target Operator (Optool0ops) op('agent').par.Optool0ops OP

The operator whose parameters will be controlled by the Agent.

Default:
"" (Empty String)
Parameters (Optool0parameters) op('agent').par.Optool0parameters StrMenu

Filter which parameters are exposed to the Agent. Use * for all parameters.

Default:
*
Menu Options:
  • Sx (Sx)
  • Sy (Sy)
Pages (Optool0pages) op('agent').par.Optool0pages StrMenu

Filter which parameter pages are exposed to the Agent. Use * for all pages.

Default:
*
Menu Options:
  • Transform (Transform)
Mode (Optool0mode) op('agent').par.Optool0mode Menu

Sets the access level for this parameter tool: disabled (off), monitor (read-only), control (read/write), forced (required in prompt).

Default:
control
Options:
disabled, monitor, control, forced
Info [ optional ] (Optool0info) op('agent').par.Optool0info Str

Additional instructions to provide to the Agent when using this parameter tool.

Default:
"" (Empty String)
Link External Tools Header
External Op Tools (Tool) op('agent').par.Tool Sequence

Sequence parameter that controls groups of external tools.

Default:
0
Active (Tool0active) op('agent').par.Tool0active Menu

Sets whether this tool is available to the Agent: disabled (off), enabled (optional), forced (required).

Default:
enabled
Options:
disabled, enabled, forced
OP (Tool0op) op('agent').par.Tool0op OP

The operator that provides the tool functionality (must have a compatible extension with GetTool method).

Default:
"" (Empty String)

Page: Context

Section titled “Page: Context”
Context Op (Contextop) op('agent').par.Contextop OP

Optional operator that can provide additional context to include in the prompt (must have GrabOpContextEXT extension).

Default:
"" (Empty String)
Use Audio (Useaudio) op('agent').par.Useaudio Toggle

When enabled, the specified audio file will be included in the prompt (for providers supporting audio input).

Default:
0
Options:
off, on
Audio File (Audiofile) op('agent').par.Audiofile File

Path to the audio file to include in the prompt.

Default:
"" (Empty String)
Send TOP Image (Sendtopimage) op('agent').par.Sendtopimage Toggle

If enabled, send the TOP specified in Topimage directly with the prompt.

Default:
0
Options:
off, on
TOP Image (Topimage) op('agent').par.Topimage TOP

Specify a TOP operator to send as an image.

Default:
"" (Empty String)

Page: I/O

Section titled “Page: I/O”
Output Mode (Outputmode) op('agent').par.Outputmode Menu

Determines how the LLM response is processed: conversation (update conversation table), table (output to DAT), parameter (set TD parameters), custom (custom handler).

Default:
conversation
Options:
conversation, table, parameter, custom
Assign Perspective (Perspective) op('agent').par.Perspective Menu

Sets how to interpret roles in the conversation: assistant (normal), user (swap user/assistant roles), or third_party (combine all messages as one).

Default:
assistant
Options:
user, assistant, third_party
Conversation Format (Conversationformat) op('agent').par.Conversationformat Menu

Controls how to format the conversation history.

Default:
input_roles
Options:
input_roles, defined_roles, clear_add_as_user, clear_add_as_assistant
Handoff Mode (Handoffmode) op('agent').par.Handoffmode Menu

Determines how to handle data passed to the Agent via the Handoff method.

Default:
default
Options:
default, use_once, hidden
Icon (Icon) op('agent').par.Icon Toggle

Show/hide the icon in the viewer.

Default:
0
Options:
off, on
Display Text (Displaytext) op('agent').par.Displaytext Toggle

Show/hide the text display in the viewer.

Default:
1
Options:
off, on
Table (Tableview) op('agent').par.Tableview Toggle

Show/hide the table view in the viewer.

Default:
0
Options:
off, on

Page: Callbacks

Section titled “Page: Callbacks”
Callbacks Header
Callback DAT (Callbackdat) op('agent').par.Callbackdat DAT

The DAT containing callback functions that respond to Agent events.

Default:
/DOC_GENERATOR/NETWORK_VIEWER/agent_callbacks1
Edit Callbacks (Editcallbacksscript) op('agent').par.Editcallbacksscript Pulse

Pulse to open the callback DAT for editing.

Default:
0
Create Callbacks (Createpulse) op('agent').par.Createpulse Pulse

Pulse to create a new callback DAT if one doesn't exist.

Default:
0
onTaskStart (Ontaskstart) op('agent').par.Ontaskstart Toggle

Enable/disable the onTaskStart callback, triggered when a new request begins.

Default:
1
Options:
off, on
onTaskComplete (Ontaskcomplete) op('agent').par.Ontaskcomplete Toggle

Enable/disable the onTaskComplete callback, triggered when a request completes successfully.

Default:
1
Options:
off, on
Ontaskerror (Ontaskerror) op('agent').par.Ontaskerror Toggle

Enable/disable the onTaskError callback, triggered when a request encounters an error.

Default:
1
Options:
off, on
onHandoff (Onhandoff) op('agent').par.Onhandoff Toggle

Enable/disable the onHandoff callback, triggered when data is passed to the Agent via the Handoff method.

Default:
1
Options:
off, on
Textport Debug Callbacks (Debugcallbacks) op('agent').par.Debugcallbacks Menu

Controls the level of callback debugging information printed to the textport.

Default:
Full Details
Options:
None, Errors Only, Basic Info, Full Details

Callbacks

Section titled “Callbacks”

The Agent operator provides several callbacks that allow you to react to different stages of its operation. Define corresponding functions in the DAT specified by the Callbackdat parameter.

Available Callbacks:
  • onTaskStart
  • onTaskComplete
  • onTaskError
  • onHandoff
Example Callback Structure: 
'''
Add custom scripts to add functionality to the Agent operator
'''

# Callback methods
def onTaskStart(info):
  """Called when a new task begins processing."""
  # Access information about the task, model, etc.
  # Example: model = info.get('model')
  pass

def onTaskComplete(info):
  """Called when a task is finished processing."""
  # Access the response, tokens used, etc.
  # Example: response = info.get('response')
  pass

def onTaskError(info):
  """Called when a task encounters an error."""
  # Access error details
  # Example: error = info.get('error')
  pass

def onHandoff(info):
  """Called when new data is handed off to the agent."""
  # Access the data handed off to the agent
  # Example: input_data = info.get('input_data')
  pass

Usage Examples

Section titled “Usage Examples”

Basic LLM Conversation

Section titled “Basic LLM Conversation”
# Set up a simple LLM conversation
op('input_table').clear()
op('input_table').appendRow(['role', 'message', 'id', 'timestamp'])
op('input_table').appendRow(['user', 'Tell me a short joke about programming', 'user1', time.time()])


# Call the agent
op('agent1').par.Call.pulse()

Using with Context Grabber

Section titled “Using with Context Grabber”
# Connect to a Context Grabber to enhance prompts with additional information
agent = op('agent1')
agent.par.Contextop = op('context_grabber1')


# Set up a conversation that will leverage the context
op('input_table').clear()
op('input_table').appendRow(['role', 'message', 'id', 'timestamp'])
op('input_table').appendRow(['user', 'Analyze the image and describe it in detail', 'user1', time.time()])


# Call with context (the context grabber will include the referenced image)
agent.par.Call.pulse()

Using Tools

Section titled “Using Tools”
# Enable tool usage
agent = op('agent1')
agent.par.Usetools = True


# Set up a parameter control tool
agent.par.Optool.numBlocks = 1
agent.par.Optool0ops = op('transform1')  # Target operator to control
agent.par.Optool0parameters = '*'  # Expose all parameters
agent.par.Optool0pages = 'Transform'  # Only from Transform page
agent.par.Optool0mode = 'control'  # Allow Agent to modify parameters
agent.par.Optool0info = 'Adjust translate and scale values as needed to center the object.'


# Ask the agent to use the tool
op('input_table').clear()
op('input_table').appendRow(['role', 'message', 'id', 'timestamp'])
op('input_table').appendRow(['user', 'Look at the scene and adjust the transform to center the object.', 'user1', time.time()])
agent.par.Call.pulse()
Section titled “Related Operators”
  • Context Grabber - Provides additional context to agents
  • Tool Builder - Create custom tools for agents to use
  • ChatTD - Core LLM integration (Agent builds upon this)