Event Mesh Entrypoints with the CLI
To create and manage Event Mesh entrypoints from the Solace Agent Mesh UI, and to understand rules, targets, and the shared model that every entrypoint type follows, see Event Mesh Entrypoints, and Configuring Entrypoints. This page covers authoring an Event Mesh entrypoint as declarative config: the YAML specific to the entrypoint kind with type: event_mesh, applied to Agent Mesh with sam config apply.
The example on this page is the same Order Processing Entrypoint that the Agent Mesh UI page builds, so you can compare the two paths directly.
Before You Start
You need a running Agent Mesh instance to apply config to. For how to install or deploy one, see Install and Deploy.
You also need event broker access: a reachable Solace event broker, ACL permissions to subscribe to every topic listed in your rules, and network connectivity from Agent Mesh to the event broker if you use an event broker other than the system event broker. For details, see the Prerequisites section of the Agent Mesh UI page.
The entrypoint references an agent or a workflow by name. The following example routes to an order-processor agent; substitute the name of an agent already deployed in your mesh. To route to a workflow instead, replace targetAgent and promptTemplate with targetWorkflowName and inputExpression.
Write the Entrypoint
An entrypoint is one file under the entrypoints/ directory of a declarative-config repo, listed by name in the manifest.
# manifest.yaml
kind: manifest
name: order-processing
description: Order-processing Event Mesh entrypoint.
target:
url: http://127.0.0.1:8800
resources:
entrypoints:
- order-processing-entrypoint
The following file defines an Event Mesh entrypoint with one event rule. spec.type is event_mesh, and the Event-Mesh-specific fields go under spec.values.
# entrypoints/order-processing-entrypoint.yaml
kind: entrypoint
name: order-processing-entrypoint
description: Routes commerce order events to the order-processor agent.
spec:
type: event_mesh
values:
broker_url: "tcps://commerce-broker.example.com:55443"
broker_vpn: commerce
broker_username: sam-entrypoint
broker_password: ${COMMERCE_BROKER_PASSWORD}
tls_skip_verify: "false"
event_rules:
- name: process_orders
subscriptions:
- topic: "commerce/orders/>"
messageFormat: json
targetAgent: order-processor
promptTemplate: "Process the following order event: {payload}"
acknowledgmentPolicy:
mode: on_completion
timeoutSeconds: 300
successOutput:
enabled: true
topic: "commerce/orders/processed"
topicType: static
responseType: full
errorOutput:
enabled: true
topic: "commerce/orders/errors"
topicType: static
The top-level name and description identify the entrypoint; description is required and must be 10 to 1,000 characters. The fields under spec.values map to the Event Mesh entrypoint form in the Agent Mesh UI:
| Field | Description |
|---|---|
broker_url
|
Event broker URI with scheme and port, for example tcps://broker.example.com:55443. Leave empty in desktop mode to fall back to the local development event broker (development and trial use only). |
broker_vpn, broker_username |
Message VPN and client username. |
broker_password
|
Event broker client password. Reference through the environment; leave the placeholder to keep the existing value on apply. |
tls_skip_verify
|
"false" (the default) validates the event broker's TLS certificate. "true" disables validation and suits development only. |
event_rules
|
The list of rules. At least one rule is required. |
Each entry under event_rules has the following shape:
| Field | Description |
|---|---|
name
|
Rule identifier, unique within the entrypoint. Allowed characters: letters, digits, _, and -. |
subscriptions
|
List of topic objects (- topic: "commerce/orders/>"). * matches one level; > matches one or more levels. Required unless existingQueueName is set, and mutually exclusive with it. |
existingQueueName
|
Name of a Solace queue that already exists on the event broker. When set, the entrypoint binds to that queue as a consumer only, adds no topic subscriptions (the queue's owner manages them), and leaves the queue in place on undeploy or delete. Required unless subscriptions is set, and mutually exclusive with it. See Binding to a Pre-Provisioned Queue for the queue permissions required on the event broker and the recommendation to use a non-exclusive queue when running more than one replica. |
messageFormat
|
Inbound payload encoding. One of json, text, xml, raw_bytes, protobuf, or structured. Defaults to json. |
targetAgent or targetWorkflowName |
Set exactly one. Names the agent or workflow that handles matching messages. |
promptTemplate
|
Template rendered against the inbound message. Required for agent targets. Not used by workflow targets, which take inputExpression instead. {payload} expands to the full payload, {topic} expands to the inbound topic, and {payload.path.to.field} extracts a field from a JSON payload. Same syntax as the Agent Mesh UI form. |
inputExpression
|
Workflow targets only. An expression that builds the workflow input. "input.payload:" delivers the whole payload as the workflow's text input (workflow.input.text), serializing a JSON payload as JSON text. If the workflow declares an input_schema, the workflow reads a JSON object payload as its input fields rather than as workflow.input.text. The exception is when the schema also accepts the payload as text and the object either does not satisfy the schema or contains a field that the schema does not declare. If the schema accepts the payload in neither form, the run fails before any node runs. Set inputExpression on every workflow target. Without it, the workflow receives empty input, which fails a schema that has required fields. |
defaultUserIdentity, userIdentityExpression |
Attribute the dispatched task to a static identity or an expression that resolves to one per message. |
acknowledgmentPolicy
|
Object with mode (on_receive or on_completion), timeoutSeconds (defaults to 300), and onFailure (action: nack or ack; nackOutcome: rejected or failed). With on_completion, when action is nack, the entrypoint returns the message to the event broker for redelivery with either nackOutcome value. |
successOutput, errorOutput |
Object with enabled, topic, topicType (static or dynamic), responseType (text, full, structured, error, or custom), and customExpression when responseType is custom. Set enabled: true on each output you want published; an output without it publishes nothing. The responseType field defaults to error on errorOutput. On successOutput, it defaults to structured for an agent target with structuredInvocation, and to text otherwise. In a dynamic topic, the entrypoint expands only {{<expression>}} blocks, such as {{text://input.payload:text}} or {{input.payload:text}}, and publishes any other text literally, including single-brace placeholders such as {id}, {payload}, and {topic}. To publish a workflow result, set responseType: custom and customExpression: "input.payload:data[0]". For how a failed workflow run appears on successOutput when errorOutput is disabled, see Outputs. |
deliveryMode, headers, userProperties (on successOutput or errorOutput) |
Delivery mode, Solace message headers, and user properties for the messages the output publishes. For more information, see Setting Delivery Mode, Headers, and User Properties. |
forwardContext, structuredInvocation, artifactProcessing |
Advanced shape extensions; see Optional Shape Extensions for the behavior. |
A queue that Agent Mesh provisions for a rule has no maximum redelivery count and no dead message queue, and the event broker immediately redelivers a message that the entrypoint negatively acknowledges. With mode: on_completion and action: nack, an event that fails every time is redelivered indefinitely. To cap redelivery, set existingQueueName to a queue configured with a maximum redelivery count and a dead message queue. For more information, see Bind to a Pre-Provisioned Queue.
Reference the event broker password through the environment so the YAML is safe to commit. Provide the real value when you run sam config apply.
To discover every field the event_mesh entrypoint type accepts, run sam config schema show entrypoint --type event_mesh. To print a templated starting file, run sam config schema example entrypoint --type event_mesh.
Setting Delivery Mode, Headers, and User Properties
By default, an output publishes each response as a Direct message that carries only the payload. To have replies follow your messaging conventions, such as sending undeliverable replies to a dead message queue, set the delivery mode, Solace message headers, and user properties on successOutput or errorOutput. The header names match the Micro-Integration message header reference, so you can use the same header names in a Micro-Integration and in an Event Mesh entrypoint.
The following example publishes each successful reply as a Guaranteed message with a time-to-live (TTL), a priority, a message type, and a correlation ID copied from a correlationId user property on the incoming event. The fields go in the process_orders entry under event_rules:
# process_orders event rule (partial)
acknowledgmentPolicy:
mode: on_completion
forwardContext:
correlationId: "input.user_properties:correlationId"
successOutput:
enabled: true
topic: "commerce/orders/processed"
topicType: static
deliveryMode: guaranteed
headers:
solace_dmqEligible: true
solace_timeToLive: 30000
solace_priority: 7
solace_applicationMessageType: order.processed
solace_correlationId: "{{text://user_data.forward_context:correlationId}}"
userProperties:
source: agent-mesh
replyText: "{{text://input.payload:text}}"
The following table describes the output fields that control how the entrypoint publishes.
| Field | Description |
|---|---|
deliveryMode
|
The direct mode (the default) publishes a Direct message without waiting for the event broker to acknowledge it. The guaranteed mode publishes a Guaranteed message and waits until the event broker acknowledges it. |
headers
|
Solace message headers, keyed by header name. |
userProperties
|
User properties, keyed by property name. A name must not start with solace.messaging., because the Solace Messaging API reads that prefix as a message setting, not as a user property. |
The entrypoint supports the following headers.
| Header | Value | Delivery mode |
|---|---|---|
solace_dmqEligible
|
Boolean. Whether the event broker can move the message to a dead message queue. A Guaranteed message is eligible when you do not set this header. | Guaranteed only |
solace_timeToLive
|
Whole number of milliseconds before the event broker discards the message or moves it to a dead message queue. | Guaranteed only |
solace_expiration
|
Expiry time, in UTC milliseconds since 1970, that the event broker passes unchanged to receiving applications without expiring the message. The Solace Messaging API ignores it when solace_timeToLive is also set. |
Guaranteed only |
solace_priority
|
Integer from 0 (lowest) to 255. | Direct or Guaranteed |
solace_correlationId
|
String. | Direct or Guaranteed |
solace_applicationMessageId
|
String. | Direct or Guaranteed |
solace_applicationMessageType
|
String. | Direct or Guaranteed |
solace_senderId
|
String. | Direct or Guaranteed |
solace_sequenceNumber
|
Whole number of 0 or more. | Direct or Guaranteed |
solace_httpContentEncoding
|
String, such as gzip. |
Direct or Guaranteed |
TTL and dead message queue handling depend on the queue that receives the reply, which you configure on the event broker, not on the entrypoint:
-
solace_timeToLivetakes effect only when the receiving queue respects message TTL. -
An expired message reaches a dead message queue only when
solace_dmqEligibleistrueor not set, and the receiving queue's dead message queue exists on the event broker.
A header or user property value is a literal, or a template when it contains a {{<expression>}} block, so a literal value cannot contain {{.
The entrypoint evaluates a template the same way as a dynamic topic. A template can read:
-
A field of the agent's response, with
input.payload:<field>, such asinput.payload:text. -
A
forwardContextvalue, withuser_data.forward_context:<key>. To copy a value from the incoming event, add it to the rule'sforwardContextand read it from there, as the preceding example does with thecorrelationIduser property.
A forwardContext expression can read the payload, topic, and user properties of the incoming event, but not its Solace message headers. You therefore cannot copy the solace_correlationId header of the incoming event to the reply.
When a template evaluates to no value, or to text that is empty or contains only whitespace, the entrypoint leaves that header or user property unset and publishes the reply without it. For example, when the rule's forwardContext has no orderId key, the value {{text://user_data.forward_context:orderId}} leaves the header or user property unset.
The entrypoint also publishes the reply without a header or user property in the following cases, so the application that receives the reply does not get that value:
-
The entrypoint cannot evaluate the template.
-
The template evaluates to a value that the header cannot take, such as
highor300forsolace_priority. -
The template evaluates to a list or object for a user property.
In each case, the entrypoint logs a warning that names the header or user property, with the message output header left unset: its value could not be used or output user property left unset: its value could not be used.
A missing value leaves the header or user property unset only when the whole value is a single {{<expression>}} or {{text://<expression>}} block. When the value has text around a block, or has more than one block, the entrypoint writes the value of each block into the text and sets the header or user property to the result.
When the value has text around a block, or has more than one block, the entrypoint can write a value in a different form from the one in the incoming event or the agent's response:
-
A missing value becomes
<nil>, except in ajson://block. For example, when the rule'sforwardContexthas noorderIdkey,id-{{text://user_data.forward_context:orderId}}becomesid-<nil>. -
A
text://block writes a number of 1,000,000 or more in exponent form. For example, when theorderIdvalue inforwardContextis1234567,id-{{text://user_data.forward_context:orderId}}becomesid-1.234567e+06, andid-{{json://user_data.forward_context:orderId}}becomesid-1234567. -
A
json://block puts quotation marks around text and writesnullfor a missing value, so use it only for a value that is always a number. -
A number with more than 15 digits can lose digits in any block. Carry a long identifier as a string, not as a number, and read it with a
text://block.
When you run sam config apply, Agent Mesh rejects, and does not save, an entrypoint whose output sets any of the following:
-
A Guaranteed-only header on an output whose
deliveryModeisdirector not set. -
The
solace_isReplyorsolace_senderTimestampheader. The entrypoint cannot set these two Micro-Integration headers on an individual message. -
A header name that is not in the preceding table of headers.
-
A literal header value that the header cannot take, such as a
solace_priorityof300or a negativesolace_timeToLive. -
A template that reads from a source that Agent Mesh does not recognize, such as
order:in{{text://order:id}}. To read a field of the agent's response, useinput.payload:, as in{{text://input.payload:order.id}}. -
A
deliveryModeother thandirectorguaranteed. -
A user property whose name starts with
solace.messaging., or whose value is a list or object.
When you run sam config plan, Agent Mesh does not check the output for any of these settings, so a plan can succeed for an entrypoint that sam config apply then rejects.
With acknowledgmentPolicy.mode: on_completion, the entrypoint acknowledges the incoming event only after the event broker acknowledges a reply sent as a Guaranteed message. If the entrypoint fails to publish a Guaranteed message, it applies the rule's acknowledgmentPolicy.onFailure.action.
With acknowledgmentPolicy.mode: on_receive, the entrypoint acknowledges the incoming event when it receives it, before it publishes any reply. If the entrypoint then fails to publish a Guaranteed message, the reply is lost, and the event broker does not redeliver the incoming event. To have the event broker redeliver the incoming event when a Guaranteed reply fails, use on_completion with onFailure.action: nack.
When the entrypoint refuses an event because a budget is spent, it acknowledges the event regardless of the acknowledgment mode, and the event broker does not redeliver it. For more information about how the entrypoint handles a spent budget, see Outputs.
A consumer may receive the same reply twice in the following cases:
-
With
acknowledgmentPolicy.mode: on_completion,onFailure.action: nack, and a Guaranteed reply, the event broker stores the reply, but the entrypoint times out waiting for the event broker to acknowledge the reply. The event broker then redelivers the incoming event, and the entrypoint runs the task again. -
With any acknowledgment mode and delivery mode, the entrypoint stops after it publishes the reply and before it finishes processing the agent's response. Another replica of the entrypoint, or the same replica after it restarts, may then process the response again and publish the same reply.
To detect a duplicate, have the consumer compare a value that comes from the incoming event, such as the solace_correlationId that the preceding example sets from forwardContext. Do not compare a value from the agent's response, because the agent may return a different response when the entrypoint runs the task again, and the consumer then misses the duplicate.
Bind to a Pre-Provisioned Queue
To have a rule consume from a Solace queue that already exists on the event broker, replace subscriptions with existingQueueName:
# entrypoints/order-processing-entrypoint.yaml
kind: entrypoint
name: order-processing-entrypoint
description: Routes commerce order events to the order-processor agent.
spec:
type: event_mesh
values:
broker_url: "tcps://commerce-broker.example.com:55443"
broker_vpn: commerce
broker_username: sam-entrypoint
broker_password: ${COMMERCE_BROKER_PASSWORD}
tls_skip_verify: "false"
event_rules:
- name: process_orders
existingQueueName: commerce/orders/order-processing
messageFormat: json
targetAgent: order-processor
promptTemplate: "Process the following order event: {payload}"
successOutput:
enabled: true
topic: "commerce/orders/processed"
errorOutput:
enabled: true
topic: "commerce/orders/errors"
The entrypoint binds to commerce/orders/order-processing as a consumer only. The queue's owner adds the topic subscriptions that fan events into it (for example, commerce/orders/>). sam config apply then deploys the entrypoint without requesting queue provisioning. For the full semantics — queue permissions, mutual exclusion with subscriptions, undeploy and delete behavior, and the recommendation to use a non-exclusive queue when running more than one replica — see Binding to a Pre-Provisioned Queue.
An entrypoint with an existingQueueName rule is managed entirely from the CLI: the Agent Mesh UI shows Entrypoint managed from the command line on its View and Edit pages, so further changes to its rules, event broker connection, or targets must come through another sam config apply.
Apply and Verify
Preview the change with sam config plan -m manifest.yaml, then apply the manifest to create and deploy the entrypoint:
export COMMERCE_BROKER_PASSWORD=... sam config apply -m manifest.yaml
Applied entrypoints: + order-processing-entrypoint created Deployments: * order-processing-entrypoint deploy (deploy) completed
Publish a message to a topic the entrypoint subscribes to and confirm the target agent receives it. To confirm the deployed configuration, export the entrypoint back into YAML with sam config pull -o ./pulled --url http://127.0.0.1:8800 --only entrypoint, or open the Agent Mesh UI and find order-processing-entrypoint in the entrypoints list on the Entrypoints page.
What Next?
You have an Event Mesh entrypoint defined as version-controllable YAML and deployed with sam config apply. Most readers next want to:
-
Define another entrypoint type as YAML: Slack Entrypoints with the CLI, Microsoft Teams Entrypoints with the CLI, or MCP Entrypoints with the CLI.
-
Configure Event Mesh entrypoints from the Agent Mesh UI: Event Mesh Entrypoints.