1. Notifications
  2. Agent Link

Notifications

Agent Link

Explains Agent Link, for stub to stub conversations, including across orgs when addressed by agent name. Covers agent profiles, sending messages, custom incoming data keys, debouncing, the _update_from_agent_link feedback action, and sessions.

WARNING

_com_platforms not supported on this notification platform. Interpolate the sessionuuid from ~~stub.data._incoming_agent_link_data.sessionuuid instead.

Overview

Agent Link lets one stub talk to another stub, as if it were an outside communication platform like Telegram or WhatsApp.

The stub that starts the conversation is the initiator. The stub it talks to is the agent. There are two ways to address an agent:

  • by agent name, which needs an Agent Link profile and routes the first message to whichever stub the profile points at. Because the name is a published address, this works across orgs as well as within your own — the profile has a whitelist of which orgs are allowed to reach it.
  • by stubref, sent in the same agent_name field, which needs no profile and talks to that one stub directly. This only works within your own org.

The initiator always addresses its messages by agent name (or stubref), whether it is starting the conversation or continuing it. Each of these messages must also set stubsession.set_new_with_timeout_hours, since that is what opens (or keeps open) the session the agent replies on. The agent has no address for the initiator, so it replies using the sessionuuid it was given, interpolating it onto every reply.

Setup

Setup only applies to agent names. A stub reached by stubref needs no profile, only the _agent_link_config described in Reaching a stub directly.

Before a stub can be reached by an agent name, it needs an Agent Link profile. You can create as many profiles as you have agents.

The profile gives the agent its name, and routes the first message of a conversation to the stub and action you specify. After that the conversation travels on its own session.

  • Navigate to Manage. Under Config select Notifications
  • Navigate to Agent Link/Agent Link Profiles
  • Click create new item
Agent name

The name other stubs use to reach this agent, and the only thing an initiator needs to know about it.

An agent name is always prefixed with your org's domain, and the field adds that prefix for you. You only fill in the part after it, which must be at least 3 words separated by full stops, with no spaces.

Filling in live.support.agent on the stubber_playground org gives the agent name stubber_playground.live.support.agent. The full name is shown above the field for you to copy into the templates that talk to it.

Because the name is how other stubs find the agent, it is worth treating it as a public address, and including something like the environment or the team in the name so it stays readable as you add more agents.

WARNING

Changing the agent name of a live profile means any template still sending to the old name will no longer find the agent. Conversations that are already open are unaffected, because they travel on their session rather than the name.

Reaching a stub directly

A stub can also be reached by its stubref, sent in the agent_name field, with no Agent Link profile needed. This only works between stubs in the same org; a stub in another org can only be reached by its actual agent name.

Because a stubref is not an address anyone published, the receiving stub has to opt in. Add _agent_link_config to its stubdata:

loading...

Without it, Agent Link messages sent to that stubref are not delivered.

The initiator then puts the stubref in the agent_name field:

loading...

Everything from there on is the same as an agent-name conversation. The receiving stub runs _update_from_agent_link, and replies by interpolating the sessionuuid it was given.

Sending messages

WARNING

Every message the initiator sends must include stubsession.set_new_with_timeout_hours. This is what opens, or keeps open, the session — without it no session exists, and the agent has no sessionuuid to reply with.

Starting a conversation

The initiator names the agent it wants. This opens a new session and delivers the message to the stub on the agent's profile.

loading...

Replying as the agent

The agent replies by interpolating the sessionuuid it was given from ~~stub.data._incoming_agent_link_data.sessionuuid. It does not need to know anything about the stub that asked.

loading...

Carrying on as the initiator

The initiator continues the conversation the same way it started it, by sending agent_name again, along with stubsession.set_new_with_timeout_hours to keep the session open. It does not need a sessionuuid — if a session is already open with that agent, the message continues it; otherwise a new one is opened.

loading...

Sending data and attachments

The message may be left out entirely, as long as there is data or attachments to deliver in its place.

loading...

A notification with no message, no data and no attachments is ignored.

Choosing where replies land

By default every message arrives in the receiving stub's data at _incoming_agent_link_data. Either side can choose a different key with two stubsession settings, sent on any message:

  • set_incoming_data_key sets where the other side's messages land on this stub.
  • set_target_incoming_data_key sets where this side's messages land on the other stub, starting with the message that carries it.

To choose where replies land on the stub that is asking, set set_incoming_data_key:

loading...

This does not change where the initiator's own messages land, so the agent still receives this message at _incoming_agent_link_data, and replies as usual:

loading...

Its replies now land on the initiator at stub.data._incoming_agent_link_data_custom. The agent can set its own key in the same way, to choose where the initiator's messages land on the agent.

To choose where a side's own messages land on the other stub, set set_target_incoming_data_key instead. The message that carries it is already delivered at the new key:

loading...

The agent receives this message, and the initiator's later ones, at stub.data.agent_links.customer. Its _incoming_agent_link_data is left as it was, so the sessionuuid to reply with is at ~~stub.data.agent_links.customer.sessionuuid.

  • The key may be a dotted path, such as agent_links.support, which delivers the payload to stub.data.agent_links.support. Only letters, numbers, _ and - are allowed in each part.
  • Both settings can be sent on the same message, and by either side.
  • Each key is remembered on the session, so it only needs to be sent once. It keeps applying to every later message in that direction, including debounce flushes, until a different key is sent. Both settings write the same stored keys, so the last one sent for a direction applies, whichever side sent it.
  • A value that isn't a usable path, such as an empty string or an unresolved ~~ placeholder, is ignored and the last key set on the session is kept.
INFO

The initiator's keys are only remembered when the session is opened or kept open, so send them alongside stubsession.set_new_with_timeout_hours.

Debouncing

When a side sends several messages in quick succession, the other stub can be told when the burst is over, so it can act once on everything it received instead of once per message. Set stubsession.debounce on the sending side:

loading...

The agent can debounce its replies in the same way, alongside its sessionuuid.

Debouncing does not hold messages back. Every message is still delivered straight away, marked as part of a burst. Once the sender has been quiet for long enough, the receiving stub gets one extra flush message to say the burst is over.

How the window works:

  • The first message opens a window that closes new_ms after it.
  • Each further message in the window pushes the close out to at least extend_ms after that message.
  • The window never stays open longer than max_ms from the first message, however many messages keep arriving.
  • When the window closes, the flush is sent to the receiving stub, using the same feedback action and data key as the messages before it.
  • If the receiving side sends a message while the sender's window is still open, the window is flushed immediately, before that message is delivered. A burst is therefore always closed off before the reply to it arrives.

Each side of a session has its own window, and only debounces when the message it sends carries stubsession.debounce. Open windows survive a restart of the service.

The receiving stub can tell the messages apart from _incoming_agent_link_data.stubsession.debounce:

Message debounce flush next_flush_ms
Part of a debounced burst true false milliseconds until the window closes
Flush, the burst is over false true 0
Sent without debouncing false false 0

A flush carries no message, data or attachments, only the sessionuuid, agent_name, stubdetails, org and stubsession.debounce. A typical pattern is to collect messages while debounce is true, and only act on them once a message with flush set to true arrives.

editor
        "_incoming_agent_link_data": {
    "sessionuuid": "e9160d64-2dc7-4892-b86b-ef603641c201",
    "agent_name": "stubber_playground.live.support.agent",
    "stubdetails": {
      "stubref": "2026-09-18-STUB-43BD",
      "stubpostref": "72ES"
    },
    "org": {
      "orguuid": "00000000-0000-0000-0000-000000000000",
      "basic": {
        "domain": "stubber_playground"
      }
    },
    "stubsession": {
      "debounce": {
        "flush": true,
        "debounce": false,
        "next_flush_ms": 0
      }
    }
  }

      

Parameters

Everything inside platforms.agent_link is a parameter for this notification.


agent_name
required from the initiator
string

The name of the agent to talk to, as set on its profile. Alternatively, the stubref of a stub to talk to directly, with no profile involved — that stub must be in your own org and must have _agent_link_config.enabled set to true in its stubdata, otherwise the message is not delivered. See Reaching a stub directly.

Send it on every message from the initiator, whether starting a conversation or continuing one already open. The initiator never needs a sessionuuid.

Default: null


stubsession
required from the initiator
object

Controls the Agent Link session. Send it on every message from the initiator.

Default: null


stubsession.set_new_with_timeout_hours
required from the initiator
integer

The number of hours the session should stay open, counted from the last message sent on it. This is what actually opens or keeps open the session — without it, no session exists and the agent has no sessionuuid to reply with.

Default: null


stubsession.set_incoming_data_key
optional
string

Where messages from the other side land in this stub's data. It does not change where this side's own messages land on the other stub. May be a dotted path, such as agent_links.support. Remembered on the session, so it applies to every later message from the other side until a different key is sent. See Choosing where replies land.

Default: _incoming_agent_link_data


stubsession.set_target_incoming_data_key
optional
string

Where this side's messages land in the other stub's data, starting with the message that carries it. It does not change where the other side's messages land on this stub. May be a dotted path, such as agent_links.support. Remembered on the session, so it applies to every later message from this side until a different key is sent. See Choosing where replies land.

Default: _incoming_agent_link_data


stubsession.debounce
optional
object

Debounces this side's messages, so the other stub is sent a flush once this side goes quiet. Values may be numbers or numeric strings. A value that isn't a usable number, such as an empty string or an unresolved ~~ placeholder, is treated as if it were left out. See Debouncing.

Default: null


stubsession.debounce.new_ms
optional
integer

How long after the first message of a burst the window closes, in milliseconds. Falls back to extend_ms when left out.

Default: extend_ms


stubsession.debounce.extend_ms
optional
integer

The least time left in the window after each further message, in milliseconds. Falls back to new_ms when left out. When neither new_ms nor extend_ms is set, or both are 0, the message is not debounced.

Default: new_ms


stubsession.debounce.max_ms
optional
integer

The longest a window can stay open, counted from the first message of the burst, in milliseconds. 0 or left out means there is no limit.

Default: 0

INFO

new_seconds, extend_seconds and max_seconds are still accepted, and are used when the matching _ms setting is left out.


sessionuuid
required from the replier
string

The session the message belongs to. The replier — the agent, answering the initiator — is given it on every message it receives, so interpolate it from ~~stub.data._incoming_agent_link_data.sessionuuid. The initiator does not send this; it addresses every message by agent_name instead.

Default: null


message
optional
string

The message delivered to the other stub. It arrives as the stubpost.message on the receiving side.

May be left out when data or attachments is supplied.

Default: null


data
optional
object

Any data you want to hand to the other stub. It arrives at _incoming_agent_link_data.data, so both sides can pass structured values around without putting them in the message.

Default: null


attachments
optional
array

The files to send along with the message, in the standard attachments format.

INFO

See Attachments for related info


Receiving messages

When another stub sends an Agent Link message to this stub, the _update_from_agent_link feedback action is triggered.

Both sides receive messages the same way, so this one action runs whether the stub is answering as the agent or receiving a reply as the initiator.

Feedback Action Data

Example data that is passed to the _update_from_agent_link feedback action:

editor
        "_incoming_agent_link_data": {
    "message": "Please check current inventory specifically for office/task chairs, including ergonomic or adjustable models. For each available option, provide SKU, price, stock, materials, dimensions, adjustment features, and other relevant specifications. Exclude the previously listed Walnut Dining Chair, since it is not an office chair.",
    "data": {
      "budget": {
        "USD": 5000
      }
    },
    "attachments": [],
    "sessionuuid": "e9160d64-2dc7-4892-b86b-ef603641c201",
    "agent_name": "stubber_playground.warehouse.demo.warehouse.furnature",
    "stubdetails": {
      "stubref": "2026-09-18-STUB-43BD",
      "stubpostref": "72ES"
    },
    "org": {
      "orguuid": "00000000-0000-0000-0000-000000000000",
      "basic": {
        "domain": "stubber_playground"
      }
    },
    "stubsession": {
      "debounce": {
        "flush": false,
        "debounce": false,
        "next_flush_ms": 0
      }
    }
  }

      

The data arrives at _incoming_agent_link_data unless this stub has chosen another key with set_incoming_data_key, or the other side has chosen one with set_target_incoming_data_key. See Choosing where replies land.

message
string

The message the other stub sent, the same value delivered as stubpost.message.


sessionuuid
string

The conversation this message belongs to. Interpolate it back onto your reply to answer whoever sent it.


agent_name
string

The agent the conversation is being held with — the agent name, or the stubref if the initiator reached this stub directly. The same value is given to both sides, so the initiator can tell which agent it is talking to.


stubdetails
object

Identifies the stub that sent this message.


stubdetails.stubref
string

The stubref of the stub that sent this message.


stubdetails.stubpostref
string

The stubpostref of the post that sent this message.


org
object

Identifies the org that sent this message.


org.orguuid
string

The orguuid of the org that sent this message.


org.basic.domain
string

The domain of the org that sent this message.


data
object

Whatever the other stub put in the data of its notification. null when no data was sent.


attachments
array

Any files the other stub sent along, in the standard attachments format. Empty when no attachments were sent.


stubsession.debounce
object

Whether this message is part of a debounced burst, or the flush that ends one. See Debouncing.


stubsession.debounce.debounce
boolean

true when the sender is debouncing and this message is part of an open burst.


stubsession.debounce.flush
boolean

true when this is the flush sent once the sender's burst is over. A flush has no message, data or attachments.


stubsession.debounce.next_flush_ms
integer

Milliseconds until the sender's window closes and the flush is sent. 0 when the message is not debounced, or is the flush itself.