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_timeToLive takes effect only when the receiving queue respects message TTL.

  • An expired message reaches a dead message queue only when solace_dmqEligible is true or 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 as input.payload:text.

  • A forwardContext value, with user_data.forward_context:<key>. To copy a value from the incoming event, add it to the rule's forwardContext and read it from there, as the preceding example does with the correlationId user 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 high or 300 for solace_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 a json:// block. For example, when the rule's forwardContext has no orderId key, id-{{text://user_data.forward_context:orderId}} becomes id-<nil>.

  • A text:// block writes a number of 1,000,000 or more in exponent form. For example, when the orderId value in forwardContext is 1234567, id-{{text://user_data.forward_context:orderId}} becomes id-1.234567e+06, and id-{{json://user_data.forward_context:orderId}} becomes id-1234567.

  • A json:// block puts quotation marks around text and writes null for 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 deliveryMode is direct or not set.

  • The solace_isReply or solace_senderTimestamp header. 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_priority of 300 or a negative solace_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, use input.payload:, as in {{text://input.payload:order.id}}.

  • A deliveryMode other than direct or guaranteed.

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