system.ai.sendMessage

This function is used in Python Scripting.

Description

Sends a one-shot prompt to a user-authored AI agent and returns the model's final text reply.

note

The Vision Client implementation is independent. There is no history threading between calls.

Client Permission Restrictions

This scripting function has no Client Permission restrictions.

Syntax

system.ai.sendMessage(agent, prompt, [modelOverride], [timeoutSecs])

Parameters

Type	Parameter	Description
String	agent	Name of the agent to send the prompt to. This value must match the agent resource name in the Gateway configuration tree.
String	prompt	The prompt to send to the agent.
String	modelOverride	Overrides the agent's configured modelId for this value. [optional]
String	timeoutSecs	This value is accepted for stability, but is not currently enforced. [optional]

Returns

String - The model's final text reply, after the agent has dispatched any tool calls.

Scope

Gateway, Vision Client, Perspective Session

Code Examples

# This script sends a one-shot prompt to an agent and prints the reply.
# The agent name must match the agent's resource name in the Gateway configuration tree.
 
reply = system.ai.sendMessage(agent = "Line 3 Troubleshooter", prompt = "Downtime on Line 3 is up this shift. What changed?")
print reply

# Similar to the Simple Message example above, except modelOverride is used to run this call against a
# different model than the one configured on the agent. The override must be a model the agent's
# Model Provider offers. The agent's configured model is unchanged for every other call.
 
reply = system.ai.sendMessage(
    agent = "Shift Report Writer",
    prompt = "Summarize the last 8 hours of alarms on Line 3 in under 100 words.",
    modelOverride = "anthropic/claude-opus-4.7"
)
print reply

# This script runs from a Gateway Timer Script and stores the reply to a tag, so that Vision Clients and
# Perspective Sessions can display the summary without calling the agent itself.
# A Gateway script has no user behind it, so it is treated as a system caller and is not checked
# against the agent's configured permissions.
 
summary = system.ai.sendMessage(agent = "Shift Report Writer", prompt = "Summarize the last 8 hours of alarms on Line 3 in under 100 words.")
system.tag.writeBlocking(["[default]Line3/ShiftSummary"], [summary])

# This script runs from a Perspective button and handles the two failures a script is most likely
# to hit: the agent name does not exist on this Gateway, and the signed-in user does not hold the
# security levels the agent requires. Both arrive as Java exceptions rather than Python ones, so
# the except clause is left blank.
 
try:
    reply = system.ai.sendMessage(agent = "Line 3 Troubleshooter", prompt = self.view.params.question)
except:
    reply = "The troubleshooting agent is unavailable. Contact your administrator."
self.getSibling("Reply").props.text = reply