Notifications

Agent Link

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

# 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.

# 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:

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

The initiator then puts the stubref in the agent_name field:

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

# 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.

# 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.

# 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.

# Sending data and attachments

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

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

# 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

# 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.

# 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:

        "_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"
      }
    }
  }

      

# 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.