@eventcatalog/core 3.41.0 → 3.41.1

package/dist/analytics/analytics.cjs

@@ -37,7 +37,7 @@ var import_axios = __toESM(require("axios"), 1);
 var import_os = __toESM(require("os"), 1);
 
 // package.json
-var version = "3.41.0";
+var version = "3.41.1";
 
 // src/constants.ts
 var VERSION = version;

package/dist/analytics/analytics.js

@@ -1,7 +1,7 @@
 import {
   raiseEvent
-} from "../chunk-TWFS6THS.js";
-import "../chunk-QVJGIQYP.js";
+} from "../chunk-6C2H2YLW.js";
+import "../chunk-X5JM6SAH.js";
 export {
   raiseEvent
 };

package/dist/analytics/log-build.cjs

@@ -111,7 +111,7 @@ var import_axios = __toESM(require("axios"), 1);
 var import_os = __toESM(require("os"), 1);
 
 // package.json
-var version = "3.41.0";
+var version = "3.41.1";
 
 // src/constants.ts
 var VERSION = version;

package/dist/analytics/log-build.js

@@ -1,9 +1,9 @@
 import {
   log_build_default
-} from "../chunk-ZN3JKTWB.js";
-import "../chunk-TWFS6THS.js";
+} from "../chunk-UGNBEYJJ.js";
+import "../chunk-6C2H2YLW.js";
 import "../chunk-3DVHEVHQ.js";
-import "../chunk-QVJGIQYP.js";
+import "../chunk-X5JM6SAH.js";
 import "../chunk-5T63CXKU.js";
 export {
   log_build_default as default

package/dist/{chunk-TWFS6THS.js → chunk-6C2H2YLW.js}

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-QVJGIQYP.js";
+} from "./chunk-X5JM6SAH.js";
 
 // src/analytics/analytics.js
 import axios from "axios";

package/dist/{chunk-DKFIEB24.js → chunk-GNLFCESR.js}

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-QVJGIQYP.js";
+} from "./chunk-X5JM6SAH.js";
 
 // src/utils/cli-logger.ts
 import pc from "picocolors";

package/dist/{chunk-ZN3JKTWB.js → chunk-UGNBEYJJ.js}

@@ -1,6 +1,6 @@
 import {
   raiseEvent
-} from "./chunk-TWFS6THS.js";
+} from "./chunk-6C2H2YLW.js";
 import {
   countResources,
   serializeCounts

package/dist/{chunk-QVJGIQYP.js → chunk-X5JM6SAH.js}

@@ -1,5 +1,5 @@
 // package.json
-var version = "3.41.0";
+var version = "3.41.1";
 
 // src/constants.ts
 var VERSION = version;

package/dist/{chunk-3R6TKNHG.js → chunk-Z5A2F2DN.js}

@@ -1,6 +1,6 @@
 import {
   logger
-} from "./chunk-DKFIEB24.js";
+} from "./chunk-GNLFCESR.js";
 import {
   cleanup,
   getEventCatalogConfigFile

package/dist/constants.cjs

@@ -25,7 +25,7 @@ __export(constants_exports, {
 module.exports = __toCommonJS(constants_exports);
 
 // package.json
-var version = "3.41.0";
+var version = "3.41.1";
 
 // src/constants.ts
 var VERSION = version;

package/dist/constants.js

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-QVJGIQYP.js";
+} from "./chunk-X5JM6SAH.js";
 export {
   VERSION
 };

package/dist/docs/development/components/components/04-agent-tools.md

@@ -0,0 +1,43 @@
+---
+sidebar_position: 2
+keywords:
+- components
+- agents
+- agent tools
+sidebar_label: AgentTools
+title: AgentTools
+description: Component for displaying the tools an agent can call in EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.41.0" />
+
+The `<AgentTools/>` component renders a table of the tools an agent can call (MCP servers, REST APIs, internal search indexes, databases, and so on).
+
+The component reads the `tools` array from the current agent's frontmatter, so it requires no props.
+
+### Use case
+
+- Display all the external capabilities an agent reaches out to at runtime.
+- Show MCP server endpoints, REST APIs, and other integrations on the agent page.
+
+**Basic Example**
+
+```jsx /agents/OrderSupportAgent/index.mdx
+<AgentTools />
+```
+
+### Output
+
+![Example output](./img/agent-tools.png)
+
+### Props
+
+The `<AgentTools/>` component takes no props — it reads the `tools` array from the current agent's frontmatter.
+
+For details on the `tools` frontmatter shape, see [Agent tools](/docs/development/guides/agents/adding-tools).
+
+### Support
+
+The `<AgentTools/>` component is supported in agent pages only. If you add it to a service, message, or domain page, the catalog will display a warning and skip the table.

package/dist/docs/development/guides/agents/01-introduction.md

@@ -0,0 +1,43 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog agents
+- AI agents
+- LLM agents
+- agent documentation
+sidebar_label: What are agents?
+title: Understanding agents
+description: Document and govern AI agents alongside your services and events.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.41.0" />
+
+In EventCatalog, agents represent AI-powered components in your architecture. They sit alongside services, messages, domains, and flows as first-class catalog resources.
+
+An agent typically wraps a large language model (LLM) and is given access to tools (MCP servers, APIs, databases) so it can take autonomous or semi-autonomous actions.
+
+![Agent detail page showing model, tools, and connected messages](./img/agent-documentation.png)
+
+## Why document agents?
+
+As AI agents take on real responsibilities in production systems they become part of your architecture whether or not they are documented.
+
+Cataloging them gives your team:
+
+- **Discoverability** — engineers and stakeholders can find what agents exist, what they do, and who owns them.
+- **Model governance** — the `model` block captures which provider, model, and snapshot version the agent runs on so drift is visible in the catalog.
+- **Tool transparency** — the `tools` array lists every external capability (MCP server, API, database) the agent can reach.
+
+## Where agents live in your architecture
+
+Agents can belong to a domain or subdomain, or sit at the root of your catalog alongside services. They participate in flows as first-class steps and appear in search, the sidebar, and the discover page.
+
+![Agent rendered as a node in the EventCatalog visualiser, connected to its tools and messages](./img/agent-visualizer.png)
+
+## Finding agents in your catalog
+
+Agents appear in the discover page alongside services, messages, domains, and flows. You can search, filter, and browse them the same way you would any other resource.
+
+![Explore page listing agents in the catalog with their owners and domains](./img/explore-agents.png)

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

@@ -0,0 +1,152 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog agents
+- AI agents
+- creating agents
+sidebar_label: Creating an agent
+title: Creating agents
+description: Creating and managing agents within EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.41.0" />
+
+Agents in EventCatalog are a great way to document AI-powered capabilities in your architecture.
+
+You can also add [tools](/docs/development/guides/agents/adding-tools) and [model metadata](/docs/development/guides/agents/model-metadata) to your agents.
+
+### What do agents look like in EventCatalog?
+
+![Example](./img/agent-documentation.png)
+
+## Adding a new agent
+
+To add a new agent, create a folder inside an `agents` directory with an `index.mdx` file.
+
+- `/agents/{Agent Name}/index.mdx`
+  - (example `/agents/FraudReviewAgent/index.mdx`)
+
+You can also place agents inside a domain or subdomain:
+
+- `/domains/{Domain Name}/agents/{Agent Name}/index.mdx`
+  - (example `/domains/Payment/agents/FraudReviewAgent/index.mdx`)
+- `/domains/{Domain Name}/subdomains/{Subdomain Name}/agents/{Agent Name}/index.mdx`
+  - (example `/domains/E-Commerce/subdomains/Payment/agents/FraudReviewAgent/index.mdx`)
+
+_Here is an example of what an agent markdown file may look like._
+
+```md title="/agents/FraudReviewAgent/index.mdx (example)"
+---
+# id of your agent, used for slugs and references in EventCatalog.
+id: FraudReviewAgent
+
+# Display name of the Agent, rendered in EventCatalog
+name: Fraud Review Agent
+
+# Version of the Agent
+version: 0.0.1
+
+# Short summary of your Agent
+summary: |
+  Reviews risky payments, explains fraud signals, and recommends whether payment processing should continue.
+
+# Optional owners, references teams or users
+owners:
+    - dboyne
+
+# Optional model metadata describing the LLM this agent runs on
+model:
+  provider: OpenAI
+  name: gpt-4.1
+  version: "2025-04-14"
+
+# Optional external tools the agent can call
+tools:
+  - name: Risk profile lookup
+    type: mcp
+    icon: /icons/tools/datadog.svg
+    url: https://mcp.example.com/fraud/risk-profile
+    description: Retrieves transaction anomaly, device fingerprint, and fraud model signals.
+
+# Optional messages this agent receives and it's version
+receives:
+  - id: PaymentInitiated
+    version: 0.0.1
+
+# Optional messages this agent sends and it's version
+sends:
+  - id: FraudReviewCompleted
+    version: 0.0.1
+
+# Optional data stores this agent reads from
+readsFrom:
+  - id: fraud-analytics-db
+    version: 0.0.1
+
+# Optional badges, rendered to UI by EventCatalog
+badges:
+    - content: AI Agent
+      backgroundColor: purple
+      textColor: purple
+---
+
+## Overview
+
+The Fraud Review Agent reviews risky payment attempts before they continue through the payment gateway.
+
+<NodeGraph />
+
+## Tools
+
+<AgentTools />
+```
+
+## Adding content
+
+With **agents** you can write any Markdown you want and it will render on your page. Every agent gets its own page.
+
+Within your markdown content you can use [components](/docs/development/components/using-components) to add interactive components to your page.
+
+## Adding tools to your agent
+
+You can document the external tools (MCP servers, APIs, databases) an agent can call.
+
+You can read more about adding tools to your agent [here](/docs/development/guides/agents/adding-tools).
+
+## Attaching an agent to a domain
+
+To associate an agent with a domain, add its `id` to the `agents` array in the domain's frontmatter:
+
+```md title="/domains/Payment/index.mdx (example)"
+---
+id: Payment
+name: Payment Domain
+version: 0.0.1
+agents:
+  - id: FraudReviewAgent
+    version: 0.0.1
+services:
+  - id: PaymentService
+    version: 0.0.1
+---
+```
+
+EventCatalog will show the agent in the domain sidebar and include it in the domain visualiser.
+
+## Custom icon
+
+Set `styles.icon` in your frontmatter to display a custom icon on the agent. The icon appears in the visualiser node, sidebar navigation, page header, and search results.
+
+```md title="/agents/FraudReviewAgent/index.mdx (example)"
+---
+id: FraudReviewAgent
+name: Fraud Review Agent
+version: 0.0.1
+styles:
+  icon: /icons/agents/fraud-review.svg
+---
+```
+
+The value can be a path to a file in your catalog's `public/` folder (e.g. `/icons/logo.svg`) or an absolute URL. [Simple Icons CDN](https://cdn.simpleicons.org) is a useful source for brand logos.

package/dist/docs/development/guides/agents/03-adding-tools.md

@@ -0,0 +1,92 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog agents
+- agent tools
+- MCP
+- AgentTools component
+sidebar_label: Agent tools
+title: Agent tools
+description: Document and display the tools an agent can call.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.41.0" />
+
+Agents often call external capabilities to do their work — MCP servers, REST APIs, internal search indexes, or databases. The `tools` array in an agent's frontmatter captures these dependencies so anyone reading the catalog can understand what the agent reaches out to at runtime.
+
+![Agent tools table rendered on an agent page](./img/agent-tools-component.png)
+
+## Define tools in frontmatter
+
+Add a `tools` array to your agent's frontmatter. Each entry describes one tool:
+
+```md title="/agents/OrderSupportAgent/index.mdx (example)"
+---
+# id of your agent, used for slugs and references in EventCatalog.
+id: OrderSupportAgent
+
+# Display name of the Agent, rendered in EventCatalog
+name: Order Support Agent
+
+# Version of the Agent
+version: 0.0.1
+
+# Optional external tools the agent can call
+tools:
+    # Display name of the tool
+  - name: Order lookup
+    # Type of tool (e.g. `mcp`, `api`) — free-form string
+    type: mcp
+    # Optional icon path (from your catalog's `public/` folder) or absolute URL
+    icon: /icons/tools/snowflake.svg
+    # Optional link to the tool endpoint or documentation
+    url: https://mcp.example.com/orders/lookup
+    # Optional short description of what the tool does
+    description: Retrieves order status, totals, shipment milestones, and recent order events from the operational read model.
+  - name: Support case notes
+    type: mcp
+    icon: /icons/tools/zendesk.svg
+    url: https://mcp.example.com/support/case-notes
+    description: Appends investigation notes, suggested customer replies, and follow-up actions to the support ticket.
+---
+```
+
+### Tool fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Display name of the tool |
+| `type` | Yes | Free-form string — use `mcp` for MCP servers, `api` for REST/HTTP endpoints, or any label that fits your stack |
+| `icon` | No | Path in your catalog's `public/` folder or an absolute URL to an icon image |
+| `url` | No | Link to the tool endpoint or documentation |
+| `description` | No | One or two sentences describing what the tool does |
+
+The `type` field is a plain string. `mcp` gets special rendering in the catalog (the MCP logo appears next to the badge), but you can use any value that is meaningful to your team.
+
+## Render tools on the page
+
+Add the [`<AgentTools />`](/docs/development/components/components/agent-tools) component anywhere in your agent's MDX body to render the tools table. The component reads the `tools` array from the current agent's frontmatter — no props needed.
+
+```md title="/agents/OrderSupportAgent/index.mdx (example)"
+---
+id: OrderSupportAgent
+# ... rest of frontmatter
+---
+
+This agent helps the support team answer order questions.
+
+## Tools
+
+<AgentTools />
+
+## Responsibilities
+
+- Summarize the current state of an order for support staff.
+```
+
+`<AgentTools />` is only supported inside agent pages. If you add it to a service or message page, the catalog will display a warning and skip the table.
+
+![Agent tools table with MCP badge and icon columns](./img/agent-tools-component.png)
+

package/dist/docs/development/guides/agents/04-model-metadata.md

@@ -0,0 +1,96 @@
+---
+sidebar_position: 4
+keywords:
+- EventCatalog agents
+- LLM model
+- model governance
+- AI governance
+sidebar_label: Model metadata
+title: Model metadata
+description: Capture the LLM provider, model, and version your agent uses.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.41.0" />
+
+Every agent can declare the LLM it uses through a `model` block in its frontmatter. This gives your team a single place to see which model powers each agent across your entire catalog.
+
+![Agents in the EventCatalog discover view](./img/explore-agents.png)
+
+## Why track the model?
+
+LLM providers release new model versions, retire old snapshots, and change behavior between releases — often without a corresponding code deployment. Capturing `provider`, `name`, and `version` makes it easy to:
+
+- Audit which agents are running on deprecated or retired snapshots.
+- Surface model drift when a provider rolls out a new default.
+- Give reviewers the context they need when an agent's output changes unexpectedly.
+
+## Add model metadata
+
+Add a `model` block to your agent's frontmatter:
+
+```md title="/agents/FraudReviewAgent/index.mdx (OpenAI example)"
+---
+id: FraudReviewAgent
+name: Fraud Review Agent
+version: 0.0.1
+
+# Optional model metadata describing the LLM this agent runs on
+model:
+  # The provider or platform powering the model
+  provider: OpenAI
+  # The model identifier
+  name: gpt-4.1
+  # The snapshot or API version of the model
+  version: "2025-04-14"
+---
+```
+
+```md title="/agents/InventoryRebalancingAgent/index.mdx (Gemini example)"
+---
+id: InventoryRebalancingAgent
+name: Inventory Rebalancing Agent
+version: 0.0.1
+
+# Optional model metadata describing the LLM this agent runs on
+model:
+  # The provider or platform powering the model
+  provider: Gemini
+  # The model identifier
+  name: gemini-2.5-pro
+  # The snapshot or API version of the model
+  version: "2025-06-17"
+---
+```
+
+```md title="/agents/ProductContentAgent/index.mdx (Anthropic example)"
+---
+id: ProductContentAgent
+name: Product Content Agent
+version: 0.0.1
+
+# Optional model metadata describing the LLM this agent runs on
+model:
+  # The provider or platform powering the model
+  provider: Anthropic
+  # The model identifier
+  name: claude-sonnet-4-5
+  # The snapshot or API version of the model
+  version: "20241022"
+---
+```
+
+### Model fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `provider` | No | The provider or platform — e.g. `OpenAI`, `Anthropic`, `Gemini`, `Azure OpenAI` |
+| `name` | No | The model identifier — e.g. `gpt-4.1`, `claude-sonnet-4-5`, `gemini-2.5-pro` |
+| `version` | No | The snapshot or API version — e.g. `2025-04-14`, `20241022` |
+
+All three fields are optional strings. Use whatever convention your provider uses for model identifiers and snapshot dates.
+
+## Model changes and versioning
+
+When you upgrade the model an agent uses, consider whether the behavior change is significant enough to warrant a new agent version. Capturing the new `model.version` in a versioned snapshot (see [Versioning](/docs/development/guides/agents/versioning-and-lifecycle/versioning)) gives your team a clear record of when the model changed and who approved it.

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.41.0";
+var version = "3.41.1";
 
 // src/constants.ts
 var VERSION = version;

package/dist/eventcatalog.js

@@ -13,8 +13,8 @@ import {
 } from "./chunk-3H2RT3CM.js";
 import {
   log_build_default
-} from "./chunk-ZN3JKTWB.js";
-import "./chunk-TWFS6THS.js";
+} from "./chunk-UGNBEYJJ.js";
+import "./chunk-6C2H2YLW.js";
 import "./chunk-3DVHEVHQ.js";
 import {
   catalogToAstro
@@ -28,13 +28,13 @@ import {
 } from "./chunk-ULZYHF3V.js";
 import {
   generate
-} from "./chunk-3R6TKNHG.js";
+} from "./chunk-Z5A2F2DN.js";
 import {
   logger
-} from "./chunk-DKFIEB24.js";
+} from "./chunk-GNLFCESR.js";
 import {
   VERSION
-} from "./chunk-QVJGIQYP.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.41.0";
+var version = "3.41.1";
 
 // src/constants.ts
 var VERSION = version;

package/dist/generate.js

@@ -1,8 +1,8 @@
 import {
   generate
-} from "./chunk-3R6TKNHG.js";
-import "./chunk-DKFIEB24.js";
-import "./chunk-QVJGIQYP.js";
+} from "./chunk-Z5A2F2DN.js";
+import "./chunk-GNLFCESR.js";
+import "./chunk-X5JM6SAH.js";
 import "./chunk-5T63CXKU.js";
 export {
   generate

package/dist/utils/cli-logger.cjs

@@ -36,7 +36,7 @@ module.exports = __toCommonJS(cli_logger_exports);
 var import_picocolors = __toESM(require("picocolors"), 1);
 
 // package.json
-var version = "3.41.0";
+var version = "3.41.1";
 
 // src/constants.ts
 var VERSION = version;

package/dist/utils/cli-logger.js

@@ -1,7 +1,7 @@
 import {
   logger
-} from "../chunk-DKFIEB24.js";
-import "../chunk-QVJGIQYP.js";
+} from "../chunk-GNLFCESR.js";
+import "../chunk-X5JM6SAH.js";
 export {
   logger
 };

package/package.json

@@ -7,7 +7,7 @@
   },
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
-  "version": "3.41.0",
+  "version": "3.41.1",
   "publishConfig": {
     "access": "public"
   },
@@ -113,9 +113,9 @@
     "update-notifier": "^7.3.1",
     "uuid": "^10.0.0",
     "zod": "^4.3.6",
-    "@eventcatalog/visualiser": "^3.22.0",
-    "@eventcatalog/linter": "1.0.25",
-    "@eventcatalog/sdk": "2.22.0"
+    "@eventcatalog/linter": "1.0.26",
+    "@eventcatalog/sdk": "2.23.0",
+    "@eventcatalog/visualiser": "^3.22.0"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.9",