# Adding messages to agents

Copy as Markdown[View as Markdown](/docs/development/guides/agents/adding-to-agents/messages.md)

***

**Added in** `eventcatalog@3.41.0`

An agent can **receive** messages (events, commands, or queries) that trigger its reasoning, and **send** messages as a result of its actions.

Connecting agents to messages keeps the full event topology visible in the visualiser and lets your team trace which agents react to which events.

![Agent visualiser showing received events, connected services, and data stores](/assets/images/agent-consuming-messages-8c8cc09285dfcf71bc7f20167cfe0dc9.png)

## Adding messages to your agent[​](#adding-messages-to-your-agent "Direct link to Adding messages to your agent")

To add messages to an agent you need to define them in either the **sends** or **receives** array within your agent frontmatter API.

You need to add the `id` of the message and optionally the `version` of the message.

/agents/FraudReviewAgent/index.mdx (example)

```
---
id: FraudReviewAgent
... # other agent frontmatter
receives:
    # id of the message this agent receives
    - id: PaymentInitiated
    # (optional) The version of the message you want to add.
    # If no version is given the latest version of the message will be used.
      version: 0.0.1
sends:
    # id of the message this agent sends
    - id: FraudCaseCreated
      version: 0.0.1
---

<!-- Markdown contents... -->
```

The **receives** and **sends** fields in your agent tell EventCatalog which messages this agent either consumes or publishes.

The power of versioning

When you define your messages for your agent you can define the version of them too. This can be powerful if you have multiple versions of your events, commands or queries. Example could be an event raised by another team — you can pin the exact version your agent reasons over so a future change doesn't silently alter its behaviour.

### Routing messages through channels[​](#routing-messages-through-channels "Direct link to Routing messages through channels")

You can also route your messages through channels. Examples of these could be your brokers, queues, topics, etc.

To do this you can use the `to` and `from` fields in your agent frontmatter.

This example shows:

* the `FraudReviewAgent` sending a `FraudCaseCreated` message to the `fraud.events` channel.
* the `FraudReviewAgent` consuming a `PaymentInitiated` message from the `payments.events` channel.

/agents/FraudReviewAgent/index.mdx (example)

```
---
id: FraudReviewAgent
... # other agent frontmatter

# Agent sends a message called FraudCaseCreated
# This message is published to the fraud.events channel (e.g broker)
sends:
  - id: FraudCaseCreated
    to:
      - id: fraud.events

# Agent consumes a message called PaymentInitiated
# This message is consumed from the payments.events channel (e.g queue)
receives:
  - id: PaymentInitiated
    from:
      - id: payments.events
---
```

You can read more about routing messages through channels in the [routing messages through channels guide](/docs/development/guides/channels/introduction.md).

### Using semver versioning[​](#using-semver-versioning "Direct link to Using semver versioning")

**Added in** `eventcatalog@2.4.0`

You can use [semver](https://semver.org/) syntax when referencing your messages in your agents.

/agents/FraudReviewAgent/index.mdx (example)

```
---
id: FraudReviewAgent
... # other agent frontmatter
receives:
    # Agent receives a message called RiskScoreCalculated
    # The latest minor/patch version of this event will be used
    - id: RiskScoreCalculated
      version: 1.x.x
sends:
    # Agent sends a message called FraudCaseCreated
    # This pulls the latest patch version of FraudCaseCreated
    - id: FraudCaseCreated
      version: 2.0.x
    # Agent sends a message called FraudEscalated
    # This pulls the latest minor/patch version of FraudEscalated
    - id: FraudEscalated
      version: >1.0.1
---

<!-- Markdown contents... -->
```

Although it's recommended to link to a version of a message it is now optional. If no version is given **latest** is used by default.

### Visualizing messages within an agent[​](#visualizing-messages-within-an-agent "Direct link to Visualizing messages within an agent")

When messages get added within your agents EventCatalog will visualize this for you either using the `NodeGraph` component or through the visualizer.

![Agent node graph showing sends and receives connections](/assets/images/agent-visualizer-f6323496caa711bd7cb50d196f9667a9.png)