---
title: "system.ai.sendMessage"
description: "Sends a one-shot prompt to a user-authored AI agent and returns the model's final text reply."
---

# system.ai.sendMessage

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

This function is used in **Python Scripting**.

## Description

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

## Client Permission Restrictions

This scripting function has no [Client Permission](../../../ignition-modules/vision/vision-project-properties/vision-project-properties.md#vision-permissions-properties) 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

```python Example #1 - Simple Message
# 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
```

```python Example #2 - Overriding the Agent's Model
# 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
```

```python Example #3 - Writing Reply to a Tag
# 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])
```

```python Example #4 - Handling a Denied or Missing Agent
# 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
```