@eventcatalog/core 3.40.2 → 3.41.1

package/dist/__mocks__/astro-content.d.cts

@@ -1,5 +1,5 @@
 declare const getCollection: (key: string, filter?: (entry: any) => boolean) => Promise<never[]>;
-type CollectionKey = 'events' | 'services' | 'commands' | 'queries' | 'domains' | 'channels' | 'flows' | 'messages' | 'entities' | 'schemas';
+type CollectionKey = 'agents' | 'events' | 'services' | 'commands' | 'queries' | 'domains' | 'channels' | 'flows' | 'messages' | 'entities' | 'schemas';
 type CollectionEntry<T extends CollectionKey> = {
     id: string;
     slug: string;

package/dist/__mocks__/astro-content.d.ts

@@ -1,5 +1,5 @@
 declare const getCollection: (key: string, filter?: (entry: any) => boolean) => Promise<never[]>;
-type CollectionKey = 'events' | 'services' | 'commands' | 'queries' | 'domains' | 'channels' | 'flows' | 'messages' | 'entities' | 'schemas';
+type CollectionKey = 'agents' | 'events' | 'services' | 'commands' | 'queries' | 'domains' | 'channels' | 'flows' | 'messages' | 'entities' | 'schemas';
 type CollectionEntry<T extends CollectionKey> = {
     id: string;
     slug: string;

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

package/dist/analytics/analytics.js

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

package/dist/analytics/count-resources.cjs

@@ -26,6 +26,7 @@ __export(count_resources_exports, {
 module.exports = __toCommonJS(count_resources_exports);
 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)"],

package/dist/analytics/count-resources.js

@@ -1,7 +1,7 @@
 import {
   countResources,
   serializeCounts
-} from "../chunk-4UVFXLPI.js";
+} from "../chunk-3DVHEVHQ.js";
 export {
   countResources,
   serializeCounts

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.40.2";
+var version = "3.41.1";
 
 // src/constants.ts
 var VERSION = version;
@@ -143,6 +143,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)"],
@@ -189,6 +190,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,

package/dist/analytics/log-build.js

@@ -1,9 +1,9 @@
 import {
   log_build_default
-} from "../chunk-5FFRK3S5.js";
-import "../chunk-PWIB7GLR.js";
-import "../chunk-4UVFXLPI.js";
-import "../chunk-HSSCHCQA.js";
+} from "../chunk-UGNBEYJJ.js";
+import "../chunk-6C2H2YLW.js";
+import "../chunk-3DVHEVHQ.js";
+import "../chunk-X5JM6SAH.js";
 import "../chunk-5T63CXKU.js";
 export {
   log_build_default as default

package/dist/catalog-to-astro-content-directory.cjs

@@ -120,6 +120,7 @@ var verifyRequiredFieldsAreInCatalogConfigFile = async (projectDirectory) => {
 // src/map-catalog-to-astro.js
 var import_node_path2 = __toESM(require("path"), 1);
 var COLLECTION_KEYS = [
+  "agents",
   "events",
   "commands",
   "services",

package/dist/catalog-to-astro-content-directory.js

@@ -1,7 +1,7 @@
 import {
   catalogToAstro
-} from "./chunk-YDXB3BD2.js";
-import "./chunk-55D645EH.js";
+} from "./chunk-O6KT4DPL.js";
+import "./chunk-IR4IAKWS.js";
 import "./chunk-5T63CXKU.js";
 export {
   catalogToAstro

package/dist/{chunk-4UVFXLPI.js → chunk-3DVHEVHQ.js}

@@ -1,6 +1,7 @@
 // src/analytics/count-resources.js
 import { glob } from "glob";
 var RESOURCE_PATTERNS = {
+  agents: ["**/agents/*/index.@(md|mdx)"],
   events: ["**/events/*/index.@(md|mdx)"],
   commands: ["**/commands/*/index.@(md|mdx)"],
   queries: ["**/queries/*/index.@(md|mdx)"],

package/dist/{chunk-K3ZVEX2Y.js → chunk-3H2RT3CM.js}

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

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

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

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

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

package/dist/{chunk-55D645EH.js → chunk-IR4IAKWS.js}

@@ -1,6 +1,7 @@
 // src/map-catalog-to-astro.js
 import path from "path";
 var COLLECTION_KEYS = [
+  "agents",
   "events",
   "commands",
   "services",

package/dist/{chunk-YDXB3BD2.js → chunk-O6KT4DPL.js}

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

package/dist/{chunk-D6IBLY3O.js → chunk-QMORF42U.js}

@@ -4,6 +4,7 @@ import path from "path";
 import { glob } from "glob";
 import matter from "gray-matter";
 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/{chunk-5FFRK3S5.js → chunk-UGNBEYJJ.js}

@@ -1,10 +1,10 @@
 import {
   raiseEvent
-} from "./chunk-PWIB7GLR.js";
+} from "./chunk-6C2H2YLW.js";
 import {
   countResources,
   serializeCounts
-} from "./chunk-4UVFXLPI.js";
+} from "./chunk-3DVHEVHQ.js";
 import {
   getEventCatalogConfigFile,
   verifyRequiredFieldsAreInCatalogConfigFile
@@ -21,6 +21,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,

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

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

package/dist/{chunk-B7LKNRMT.js → chunk-Z5A2F2DN.js}

@@ -1,6 +1,6 @@
 import {
   logger
-} from "./chunk-D6UVZABG.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.40.2";
+var version = "3.41.1";
 
 // src/constants.ts
 var VERSION = version;

package/dist/constants.js

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-HSSCHCQA.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.