@eventcatalog/core 3.40.2 → 3.41.1

package/dist/docs/development/guides/agents/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Agents",
+  "position": 4,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/agents",
+    "description": "A collection of guides to help you understand agents and how they work with EventCatalog."
+  }
+}

package/dist/docs/development/guides/agents/adding-to-agents/01-messages.md

@@ -0,0 +1,122 @@
+---
+keywords:
+- EventCatalog agents
+- agent messages
+- sends receives
+sidebar_label: Messages
+title: Adding messages to agents
+description: Connecting agents to the messages they produce and consume.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="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](../img/agent-consuming-messages.png)
+
+## 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.
+
+```md title="/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.
+
+:::info 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
+
+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.
+
+```md title="/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).
+
+### Using semver versioning
+
+<AddedIn version="2.4.0" />
+
+You can use [semver](https://semver.org/) syntax when referencing your messages in your agents.
+
+```md title="/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
+
+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](../img/agent-visualizer.png)

package/dist/docs/development/guides/agents/adding-to-agents/02-datastores.md

@@ -0,0 +1,62 @@
+---
+keywords:
+- EventCatalog agents
+- agent data stores
+- writesTo readsFrom
+sidebar_label: Data stores
+title: Adding data stores to agents
+description: Document the data stores an agent reads from or writes to.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.41.0" />
+
+[Data stores](/docs/development/guides/data/introduction) are containers that hold data in your architecture — databases, caches, object stores, search indexes, and so on. Agents can read from and write to these containers, and documenting those relationships keeps the full data-access picture visible in the visualiser.
+
+## Specify read/write relationships
+
+Add `readsFrom` or `writesTo` arrays to your agent's frontmatter. Provide the `id` of the data store and optionally its `version`.
+
+```md title="/agents/FraudReviewAgent/index.mdx (example)"
+---
+id: FraudReviewAgent
+version: 0.0.1
+readsFrom:
+  - id: fraud-analytics-db
+  - id: ml-model-store
+    version: 2.0.0
+---
+```
+
+```md title="/agents/InventoryRebalancingAgent/index.mdx (example)"
+---
+id: InventoryRebalancingAgent
+version: 0.0.1
+readsFrom:
+  - id: inventory-readmodel
+  - id: inventory-db
+writesTo:
+  - id: rebalancing-audit-log
+---
+```
+
+If no version is provided, EventCatalog uses the latest version of the data store.
+
+## Visualize data stores
+
+When data stores are connected to an agent, EventCatalog visualizes the read/write relationships — either via the `<NodeGraph />` component on the agent page or through the full-screen visualiser.
+
+![Agent visualiser showing data store nodes connected with reads and writes](../img/agent-consuming-messages.png)
+
+You can also control the **Containers** section in the agent's sidebar using `detailsPanel`:
+
+```md title="/agents/FraudReviewAgent/index.mdx (example)"
+---
+id: FraudReviewAgent
+version: 0.0.1
+detailsPanel:
+  containers:
+    visible: false
+---
+```

package/dist/docs/development/guides/agents/adding-to-agents/_category_.json

@@ -0,0 +1,10 @@
+{
+  "label": "Adding to agents",
+  "position": 7,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/adding-to-agents"
+  }
+}

package/dist/docs/development/guides/agents/ownership/01-owners.md

@@ -0,0 +1,67 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog
+- agents
+- owners
+sidebar_label: Owners
+title: Adding agent owners
+description: Adding owners to agents with EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.41.0" />
+
+Owners in EventCatalog are either **users** or **teams** and are optional. Assigning owners to an agent makes it clear who is responsible for keeping it up to date, responding to incidents, and approving model upgrades.
+
+## Add owners using frontmatter
+
+Add the `id` of any user or team to the `owners` array in your agent's frontmatter:
+
+```md title="/agents/FraudReviewAgent/index.mdx (example)"
+---
+id: FraudReviewAgent
+version: 0.0.1
+owners:
+  - dboyne      # a user id
+  - full-stack  # a team id
+---
+```
+
+:::tip Creating users and teams
+EventCatalog gives you the ability to create users and teams. You can read the documentation to get started.
+:::
+
+## Show owned agents on a team page
+
+<AddedIn version="3.41.0" />
+
+Teams and users gained an `ownedAgents` array alongside `ownedServices`. Add agent references to a team file to surface owned agents directly on the team's catalog page.
+
+```md title="/teams/full-stack.mdx (example)"
+---
+id: full-stack
+name: Full Stack Team
+ownedAgents:
+  - id: FraudReviewAgent
+    version: 0.0.1
+  - id: OrderSupportAgent
+ownedServices:
+  - id: PaymentService
+    version: 0.0.1
+---
+```
+
+The same field is available on user files:
+
+```md title="/users/dboyne.mdx (example)"
+---
+id: dboyne
+name: David Boyne
+ownedAgents:
+  - id: InventoryRebalancingAgent
+---
+```
+
+If no `version` is provided, EventCatalog uses the latest version of the agent.

package/dist/docs/development/guides/agents/ownership/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Ownership",
+  "position": 6,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/agents-ownership",
+    "description": "A collection of guides to help you manage ownership of agents in EventCatalog."
+  }
+}

package/dist/docs/development/guides/agents/versioning-and-lifecycle/01-versioning.md

@@ -0,0 +1,48 @@
+---
+keywords:
+- versioning
+- agents
+sidebar_label: Versioning
+title: Versioning
+description: Learn how to version agents in EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.41.0" />
+
+All content in EventCatalog can be versioned. Versioning an agent lets you keep a historic snapshot whenever the agent's model, tools, or message connections change in a meaningful way.
+
+## Version an agent
+
+1. Create a `/versioned` directory inside your agent folder if one does not exist yet.
+1. Create a new folder with the version number you are archiving.
+    - Example: `/agents/FraudReviewAgent/versioned/0.0.1`
+1. Copy `index.mdx` (and any other files) into that folder.
+    - Example: `/agents/FraudReviewAgent/versioned/0.0.1/index.mdx`
+    - The `version` inside this file should match `0.0.1`.
+1. Bump the `version` in the root `index.mdx` to the next release.
+    - Example: change `version: 0.0.1` to `version: 0.0.2` in `/agents/FraudReviewAgent/index.mdx`.
+
+```
+agents/
+  FraudReviewAgent/
+    index.mdx          ← current version (0.0.2)
+    versioned/
+      0.0.1/
+        index.mdx      ← archived snapshot
+```
+
+## Navigate versions
+
+EventCatalog creates version links automatically on every agent page. Users can also navigate directly by adding the version to the URL (e.g. `/docs/agents/FraudReviewAgent/0.0.1` loads the `0.0.1` snapshot).
+
+## When to version
+
+Consider creating a new version when you:
+
+- Upgrade the underlying LLM to a new model or snapshot.
+- Add or remove a tool that changes what the agent can reach.
+- Change the messages the agent consumes or produces.
+
+Smaller documentation edits (fixing typos, improving descriptions) do not need a new version.

package/dist/docs/development/guides/agents/versioning-and-lifecycle/02-changelog.md

@@ -0,0 +1,40 @@
+---
+keywords:
+- changelog
+- agents
+sidebar_label: Adding a changelog
+title: Agent changelogs
+description: Adding changelogs to agents in EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.41.0" />
+
+EventCatalog supports changelogs for agents. When you version an agent you can attach a `changelog.mdx` to capture what changed and why.
+
+## Add a changelog
+
+1. Add a `changelog.mdx` to your agent folder (or a versioned snapshot):
+    - Current version: `/agents/{Agent}/changelog.mdx`
+    - Versioned snapshot: `/agents/{Agent}/versioned/0.0.1/changelog.mdx`
+
+```md title="/agents/FraudReviewAgent/changelog.mdx (example)"
+---
+createdAt: 2025-06-01
+badges:
+  - content: Model upgrade
+    backgroundColor: purple
+    textColor: purple
+---
+
+### Upgraded to GPT-4.1
+
+The agent now runs on `gpt-4.1` (snapshot `2025-04-14`). Response latency for fraud signal explanations dropped by ~30% compared to the previous model. No changes to tools or message connections.
+```
+
+Navigate to the changelog by clicking the **Changelog** button on the agent page, or visit `/docs/agents/{Agent}/{version}/changelog` directly.
+
+## Why add changelogs?
+
+Changelogs give your team the context behind model upgrades, tool additions, and prompt changes. They are especially valuable for agents because behavior can shift when the underlying model changes even without a code deployment.

package/dist/docs/development/guides/agents/versioning-and-lifecycle/03-deprecating.md

@@ -0,0 +1,41 @@
+---
+keywords:
+- EventCatalog
+- agents
+- deprecation
+sidebar_label: Deprecating agents
+title: Deprecating agents
+description: Deprecating agents with EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.41.0" />
+
+Any resource in EventCatalog can be deprecated. Deprecating an agent displays a banner on its page so consumers know it is no longer actively maintained.
+
+## Deprecate using frontmatter
+
+Add the `deprecated` field to your agent's frontmatter:
+
+```md title="/agents/FraudReviewAgent/index.mdx (example)"
+---
+id: FraudReviewAgent
+version: 0.0.1
+
+# Deprecated as an object (recommended — gives a date and reason)
+deprecated:
+  date: 2025-09-01
+  message: |
+    This agent has been replaced by **FraudReviewAgentV2**, which uses the updated risk scoring pipeline.
+    Contact the [Payments team](mailto:payments@example.com) for migration guidance.
+
+# Or deprecated as a simple boolean
+deprecated: true
+---
+```
+
+Using an object is recommended because it gives readers a date and a reason. The `date` can be in the past (already deprecated) or the future (will be deprecated).
+
+- `deprecated.date` — Date in `YYYY-MM-DD` format.
+- `deprecated.message` — Markdown string explaining why the agent is deprecated and what to use instead.

package/dist/docs/development/guides/agents/versioning-and-lifecycle/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Versioning & lifecycle",
+  "position": 5,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/agents-versioning-and-lifecycle",
+    "description": "A collection of guides to help you version and manage the lifecycle of agents in EventCatalog."
+  }
+}

package/dist/docs/development/guides/domains/02-creating-domains/03-adding-services-to-domains.md

@@ -88,3 +88,30 @@ When you view your domain in EventCatalog, the services will be visualized for y
 
 You can make as many changes as you want, but if you are adding/removing services you may want to consider versioning your domain. This allows you to keep historic changes, and let others understand why services are coming in/out of a particular domain.
 
+## Add agents to a domain
+
+<AddedIn version="3.41.0" />
+
+[Agents](/docs/development/guides/agents/introduction) can be attached to a domain the same way services can. Add an `agents` array to your domain's frontmatter:
+
+```md title="/domains/Payment/index.mdx (example)"
+---
+id: Payment
+name: Payment Domain
+version: 0.0.1
+services:
+  - id: PaymentService
+    version: 0.0.1
+agents:
+  - id: FraudReviewAgent
+    version: 0.0.1
+  # version is optional — latest is used if omitted
+  - id: AnotherAgent
+---
+
+<!-- Markdown content... -->
+
+```
+
+EventCatalog will show the agents in the domain sidebar and include them in the domain visualiser alongside services.
+

package/dist/docs/development/guides/flows/03-flow-nodes.md

@@ -64,6 +64,7 @@ next_steps:
 - [externalSystem](#externalsystem) — Represents an external system in your flow diagram
 - [message](#message) — Represents an event, command or query resource in EventCatalog
 - [service](#service) — Represents a service resource in EventCatalog
+- [agent](#agent) — Represents an agent resource in EventCatalog (added in EventCatalog 3.41.0)
 - [flow](#flow) — Represents a flow in EventCatalog (added in EventCatalog 2.34.2)
 - [container](#container) — Represents a data store (container) resource in EventCatalog
 - [dataProduct](#dataproduct) — Represents a data product resource in EventCatalog
@@ -172,6 +173,35 @@ steps:
 
 ---
 
+### agent {#agent}
+
+<AddedIn version="3.41.0" />
+
+Represents and refers to an [agent](/docs/development/guides/agents/introduction) resource in EventCatalog. Agents render as purple/violet nodes in the visualiser so they are easy to distinguish from services. When a flow references an agent, the agent's page shows a back-link to the flow.
+
+#### Agent properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `id` | `string` | **Yes** | The id of the agent in your catalog |
+| `version` | `string` | No | The version to reference (defaults to `latest`) |
+
+```yml
+steps:
+  - id: "fraud_review"
+    title: "Fraud Review Agent"
+    agent:
+      id: "FraudReviewAgent"
+      version: "0.0.1"
+    next_steps:
+      - id: "payment_approved"
+        label: "Approved"
+      - id: "payment_declined"
+        label: "Declined"
+```
+
+---
+
 ### flow
 
 <AddedIn version="2.34.2" />

package/dist/eventcatalog.cjs

@@ -114,7 +114,7 @@ var verifyRequiredFieldsAreInCatalogConfigFile = async (projectDirectory) => {
 var import_picocolors = __toESM(require("picocolors"), 1);
 
 // package.json
-var version = "3.40.2";
+var version = "3.41.1";
 
 // src/constants.ts
 var VERSION = version;
@@ -238,6 +238,7 @@ async function raiseEvent(eventData) {
 // src/analytics/count-resources.js
 var import_glob = require("glob");
 var RESOURCE_PATTERNS = {
+  agents: ["**/agents/*/index.@(md|mdx)"],
   events: ["**/events/*/index.@(md|mdx)"],
   commands: ["**/commands/*/index.@(md|mdx)"],
   queries: ["**/queries/*/index.@(md|mdx)"],
@@ -284,6 +285,7 @@ var getFeatures = async (configFile) => {
 };
 var CLOUD_ANALYTICS_ENDPOINT = "https://api.ecingest.dev/v1/analytics/ingest";
 var toCloudResourceCounts = (counts) => ({
+  agents: counts.agents || 0,
   domains: counts.domains || 0,
   services: counts.services || 0,
   events: counts.events || 0,
@@ -356,6 +358,7 @@ var import_node_fs2 = __toESM(require("fs"), 1);
 // src/map-catalog-to-astro.js
 var import_node_path3 = __toESM(require("path"), 1);
 var COLLECTION_KEYS = [
+  "agents",
   "events",
   "commands",
   "services",
@@ -1323,6 +1326,7 @@ var import_node_path8 = __toESM(require("path"), 1);
 var import_glob4 = require("glob");
 var import_gray_matter4 = __toESM(require("gray-matter"), 1);
 var RESOURCE_COLLECTIONS = {
+  agents: { docsPath: "agents", type: "Agent" },
   channels: { docsPath: "channels", type: "Channel" },
   commands: { docsPath: "commands", type: "Command" },
   containers: { docsPath: "containers", type: "Container" },

package/dist/eventcatalog.config.d.cts

@@ -190,6 +190,7 @@ interface Config {
         };
     };
     dependencies?: {
+        agents?: ResourceDependency[];
         commands?: ResourceDependency[];
         events?: ResourceDependency[];
         services?: ResourceDependency[];
@@ -246,6 +247,9 @@ interface Config {
     events?: {
         tableConfiguration?: TableConfiguration;
     };
+    agents?: {
+        tableConfiguration?: TableConfiguration;
+    };
     services?: {
         tableConfiguration?: TableConfiguration;
     };

package/dist/eventcatalog.config.d.ts

@@ -190,6 +190,7 @@ interface Config {
         };
     };
     dependencies?: {
+        agents?: ResourceDependency[];
         commands?: ResourceDependency[];
         events?: ResourceDependency[];
         services?: ResourceDependency[];
@@ -246,6 +247,9 @@ interface Config {
     events?: {
         tableConfiguration?: TableConfiguration;
     };
+    agents?: {
+        tableConfiguration?: TableConfiguration;
+    };
     services?: {
         tableConfiguration?: TableConfiguration;
     };

package/dist/eventcatalog.js

@@ -7,19 +7,19 @@ import {
 } from "./chunk-WAJIJEI3.js";
 import {
   buildSearchIndex
-} from "./chunk-D6IBLY3O.js";
+} from "./chunk-QMORF42U.js";
 import {
   watch
-} from "./chunk-K3ZVEX2Y.js";
+} from "./chunk-3H2RT3CM.js";
 import {
   log_build_default
-} from "./chunk-5FFRK3S5.js";
-import "./chunk-PWIB7GLR.js";
-import "./chunk-4UVFXLPI.js";
+} from "./chunk-UGNBEYJJ.js";
+import "./chunk-6C2H2YLW.js";
+import "./chunk-3DVHEVHQ.js";
 import {
   catalogToAstro
-} from "./chunk-YDXB3BD2.js";
-import "./chunk-55D645EH.js";
+} from "./chunk-O6KT4DPL.js";
+import "./chunk-IR4IAKWS.js";
 import {
   getProjectOutDir,
   isAuthEnabled,
@@ -28,13 +28,13 @@ import {
 } from "./chunk-ULZYHF3V.js";
 import {
   generate
-} from "./chunk-B7LKNRMT.js";
+} from "./chunk-Z5A2F2DN.js";
 import {
   logger
-} from "./chunk-D6UVZABG.js";
+} from "./chunk-GNLFCESR.js";
 import {
   VERSION
-} from "./chunk-HSSCHCQA.js";
+} from "./chunk-X5JM6SAH.js";
 import {
   getEventCatalogConfigFile,
   verifyRequiredFieldsAreInCatalogConfigFile

package/dist/generate.cjs

@@ -78,7 +78,7 @@ var getEventCatalogConfigFile = async (projectDirectory) => {
 var import_picocolors = __toESM(require("picocolors"), 1);
 
 // package.json
-var version = "3.40.2";
+var version = "3.41.1";
 
 // src/constants.ts
 var VERSION = version;

package/dist/generate.js

@@ -1,8 +1,8 @@
 import {
   generate
-} from "./chunk-B7LKNRMT.js";
-import "./chunk-D6UVZABG.js";
-import "./chunk-HSSCHCQA.js";
+} from "./chunk-Z5A2F2DN.js";
+import "./chunk-GNLFCESR.js";
+import "./chunk-X5JM6SAH.js";
 import "./chunk-5T63CXKU.js";
 export {
   generate

package/dist/map-catalog-to-astro.cjs

@@ -35,6 +35,7 @@ __export(map_catalog_to_astro_exports, {
 module.exports = __toCommonJS(map_catalog_to_astro_exports);
 var import_node_path = __toESM(require("path"), 1);
 var COLLECTION_KEYS = [
+  "agents",
   "events",
   "commands",
   "services",

package/dist/map-catalog-to-astro.js

@@ -1,6 +1,6 @@
 import {
   mapCatalogToAstro
-} from "./chunk-55D645EH.js";
+} from "./chunk-IR4IAKWS.js";
 export {
   mapCatalogToAstro
 };