AI Agents

An AI agent is a multi-step assistant. It reads the conversation, plans, calls tools (your AI tools, MCP tools and a knowledge-base search), looks at the results, and calls the model again until it has an answer. The Create AI Chat Completion node makes a single model call and replies; the AI Agent node can keep working through several model and tool calls, within limits you set, before it answers.

Use an agent when a request needs several steps, for example "find the customer's order, check its delivery status and offer a new date". For a direct answer from instructions and a knowledge base, the AI node is simpler and cheaper.

The building blocks

Part	What it is	Where you set it
AI Harness	The engine that runs the agent loop: MonoChat's own, an agent SDK, or a hosted agent service.	Settings › Automation › AI Harnesses
Models	The AI models the agent thinks with: a main model, an optional fallback model and an optional fast model. Hosted harnesses use their own provider's models instead.	The AI Agent node
Tools	AI scopes, AI Tool functions and MCP tools.	The AI Agent node
Execution Budget	Limits on model calls, tool calls, tokens, duration and retries for each run.	The AI Agent node
Run	One execution of the agent. Every run is recorded in AI Agent Runs.	Created by the node or the API

AI Harnesses

Settings › Automation › AI Harnesses lists the harnesses your agents can run on: the ones MonoChat offers to every workspace, and the ones you add with your own credentials.

Harness	Where it runs	Models it uses	Who adds it
MonoChat Native	Inside MonoChat	Your AI models	MonoChat
OpenAI Agents SDK	Inside MonoChat	Your AI models	MonoChat
Claude Agent SDK	On the MonoChat agent runner	Your AI models	MonoChat
pi	On the MonoChat agent runner	Your AI models	MonoChat
OpenAI Agents API	In OpenAI's cloud	The harness's allowed models	You, with your OpenAI API key (MonoChat may offer one too)
Claude Managed Agents	In Anthropic's cloud	The harness's allowed models	You, with your Anthropic API key (MonoChat may offer one too)
Custom Endpoint	On your own server	Your AI models (optional)	You, with your endpoint and secret

Harnesses that run on MonoChat are offered by MonoChat; your workspace can only add harnesses that take its own credentials. Claude Agent SDK and pi need MonoChat's agent runner: where it is not set up, a run on them fails with "This harness is not available on this server."

Whatever the harness, MonoChat stays in control: every model call of a harness that uses your AI models goes through MonoChat (so billing and the budget apply), every tool call runs your functions, MCP tools and AI scopes in your workspace, and the budget is enforced on every harness.

Add a harness

1. Go to Settings › Automation › AI Harnesses and click + (Create).
2. Enter a Name and, optionally, a Description.
3. Choose the Harness. Each option says where it runs.
4. Under Credentials, enter what the harness needs:
   • OpenAI Agents API, Claude Managed Agents: API Key.
   • Custom Endpoint: Endpoint and API Key.
5. For a hosted harness, fill in Allowed Models: enter the provider's model names (for example the OpenAI or Anthropic model ID). Use Add Model for up to 10 models. Agents on this harness can only choose from this list.
6. Click Save.

When you edit a harness, the Harness type cannot be changed, and the key field reads API Key (leave empty to keep the saved key).

Claude Managed Agents

The first time a harness of this type is used, MonoChat creates one agent and one environment in that Anthropic account and reuses them afterwards.

Custom Endpoint

A Custom Endpoint harness sends runs to your own service, for example a self-hosted agent. For each run MonoChat sends a POST to <Endpoint>/runs with Authorization: Bearer <API Key>. The body contains the run ID, the instructions, the input, the conversation messages, the budget, the model aliases (agent-main, agent-fallback, agent-fast) and three URLs with a token for this run:

• a model gateway (OpenAI-compatible …/v1 and Anthropic-compatible base URLs) that calls the node's AI models and enforces the budget,
• an MCP server that exposes the run's tools,
• an events URL where your service reports the result (completed with result, or failed with error).

The run's token stops working when the run ends.

The AI Agent node

Add an agent to a flow with the AI Agent node, under the hybrid nodes in the flow designer. See Flows for how to add and connect nodes.

Fields

Section	Field	Description
	Name	The node name shown on the canvas.
	AI Harness	Required. The harness that runs the agent.
	Instructions	The agent's system instructions: its role, tone, rules and what it may or may not do.
	Task (added to the agent instructions; tags can be used)	What this node asks the agent to do. It is added after the instructions and can use the same tags as the AI node's prompt, for example to include customer data.
Models	Main Model	The model the agent uses. Required for every harness except Custom Endpoint.
	Fallback Model (after the soft limit)	The model the agent switches to once it reaches the soft limit of model calls, typically a cheaper or faster model.
	Fast Model (light background tasks)	A model a harness can use for its light background calls.
	Model (one of the harness's allowed models)	Shown instead of the three fields above for a hosted harness.
Agent Session	Session	Continue the existing agent session (default) or Start a new agent session. See Agent sessions.
	Task Key (separate agent sessions per task)	Optional. Keeps a separate agent session per key in the same conversation, for example booking and support.
	Message History Limit	How many conversation messages the agent receives.
	Speech to Text AI Models	A model with Transcript. Voice messages in the conversation reach the agent as text.
Tool Settings	AI Scopes	Knowledge bases the agent can search. They are offered to the agent as a knowledge-base search tool.
	AI Tool	Functions of type AI Tool the agent can call.
	Set AI MCP Client Content Tools	Opens the drawer where you add MCP tools. See MCP Clients.
Messages	Forward Intermediate Messages to the Customer	Off by default. What the agent writes while it is still working (for example "Let me check your order") is sent to the customer when on; when off it is added to the session as a whisper message only your team sees.
	Send answer	On by default. Sends the agent's final answer to the customer. Turn it off to use the answer only inside the flow.
Execution Budget	Max Model Calls	Default 4.
	Soft Limit: Model Calls	Optional. After this many model calls the agent switches to the fallback model. Must be lower than Max Model Calls and needs a fallback model.
	Max Tool Calls	Default 6. With 0, the run ends as Budget Exceeded as soon as the agent tries to call a tool.
	Max Total Tokens	Default 20000. Input and output tokens of all model calls in the run.
	Max Duration (Seconds)	Default 30.
	Max Retries	Default 2. How many times a failed model call is retried.

tip

Write the stable rules in Instructions and the specific job of this step in Task. That way several AI Agent nodes in a flow can share the same instructions and differ only in their task.

warning

Hosted harnesses do not support a soft limit, because they cannot switch to a fallback model. Leave Soft Limit: Model Calls empty for them.

What happens when the flow reaches the node

1. MonoChat checks your balance and the node's settings, and starts a run. The run is Queued, then Running. The flow instance waits on the node.
2. The agent receives the instructions and the task, and, when the flow belongs to a conversation, the conversation's messages up to the Message History Limit, with voice messages transcribed.
3. The agent calls models and tools until it has an answer or a limit is reached. Text it writes between tool calls is handled as an intermediate message.
4. When the run ends:
   • if it Completed and Send answer is on, the answer is sent to the customer. Long answers are split into several messages when they exceed the channel's limit (4096 characters on WhatsApp);
   • if it ended any other way, a whisper message "AI agent run ended: status. error" is added to the session for your team.
5. The flow continues on the output that matches how the run ended.

Runs of the same agent session are processed one at a time, in order.

Outputs

Output	When
Completed	The agent finished with an answer.
Budget Exceeded	The run used up Max Model Calls, Max Tool Calls or Max Total Tokens.
Timed Out	The run reached Max Duration (Seconds).
Hate, Jailbreak, Self Harm, Sexual, Violence	The model provider's content filter stopped the run for this category. These are the same outputs the AI node has.
On Fail	The run failed for any other reason, or was cancelled. A content-filter stop also goes here on nodes saved before these outputs existed; open and save such a node to get them.

Connect at least Completed and On Fail. A common pattern is to send Budget Exceeded, Timed Out and On Fail to an Assign Session node so a teammate takes over.

Agent sessions

An agent session is the agent's memory across runs. MonoChat keeps one active agent session per conversation, harness and task key.

• Continue the existing agent session reuses it, so the agent picks up where it left off. On hosted harnesses the provider's own session continues too.
• Start a new agent session closes the active one and starts fresh, for example at the beginning of a new topic.
• A Task Key keeps independent sessions side by side in the same conversation.

Billing

• Model calls on AI models provided by MonoChat are billed from your balance as usual. Calls on your own models are billed by your provider.
• A harness provided by MonoChat can add its own fees per run, per minute and per tool call, and, for a hosted harness, the tokens its provider reports. They appear in Transactions as AI Agent Run, AI Agent Duration, AI Agent Tool Call and AI token categories.
• A harness you add with your own credentials has no MonoChat fee; its provider bills you.
• A run does not start when your balance is insufficient.

AI Agent Run Finished event

AI Agent Run Finished is an event node. It fires when a run tied to a customer ends, whether the run was started by a flow or through the API with a session. Like other event nodes it has optional Condition and Timeout settings. Use it to start a separate flow after agent runs, for example to log results or notify a team.

Start an agent from code

Custom functions and API clients can run agents with these methods (permission Start / Read / Cancel AI agent runs in automation):

Method	What it does
business.tenants.automation.ai.aiAgentRuns.create	Starts a run. Returns aiAgentRunId and aiAgentSessionId.
business.tenants.automation.ai.aiAgentRuns.show	Returns a run (_id) with its status, usage, steps and result.
business.tenants.automation.ai.aiAgentRuns.cancel	Cancels a queued or running run (_id).

create takes aiHarnessClientId, input (the task), optionally sessionId (to work in a conversation), aiAgentSessionId, taskKey and isNewSession, and options with the same settings as the node: instructions, aiModelClientId, fallbackAiModelClientId, fastAiModelClientId, harnessModel, toolCustomFunctionIds, aiScopeIds, aiMcpClientDatas, messageHistoryLimit, speechToTextAiModelClientId, forwardIntermediateMessages, willSendAnswer and a required budget. Through the API, forwardIntermediateMessages and willSendAnswer default to false.

const { aiAgentRunId } = await sdk.method({ name: 'business.tenants.automation.ai.aiAgentRuns.create' }).callAsync({
  payload: {
    aiHarnessClientId: 'HARNESS_ID',
    input: 'Summarise the open orders of this customer.',
    sessionId: 'SESSION_ID',
    options: {
      instructions: 'You are the order assistant of our store.',
      aiModelClientId: 'MODEL_ID',
      toolCustomFunctionIds: ['FUNCTION_ID'],
      budget: { maxLlmCalls: 4, maxToolCalls: 6, maxTotalTokens: 20000, maxDurationSeconds: 30, maxRetries: 2 },
    },
  },
})

The run is asynchronous: read it later with show, or react to it with the AI Agent Run Finished event. Without a sessionId, each call starts a new agent session unless you pass the aiAgentSessionId a previous call returned; the agent then sees the earlier completed runs of that agent session as its history. See Method for calling methods from a function.

Permissions

Permission	Allows
Read / Create / Update / Delete AI harnesses in automation	Managing AI Harnesses
Read AI agent runs in automation	Seeing AI Agent Runs
Start AI agent runs in automation	Calling aiAgentRuns.create
Cancel AI agent runs in automation	Calling aiAgentRuns.cancel

See Roles.

Related

• AI Agent Runs: see what each run did
• AI Models
• MCP Clients
• AI Scopes
• Flows