Agent frontmatter API

View as Markdown

---

Added in eventcatalog@3.41.0

Overview

Agents are MDX files with frontmatter. They represent AI agents in your architecture — the model that powers them, the tools they use, and the messages, data stores, and flows they interact with.

Here is an example of the agent frontmatter you will find in your /agents folder.

/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

# Short summary of the agent
summary: |
  Assists support teams by investigating customer order questions and suggesting the next best action.

# Optional owners, references teams or users
owners:
  - dboyne
  - order-management

# Optional model that powers the agent
model:
  provider: OpenAI
  name: gpt-4.1-mini
  version: "2025-04-14"

# Optional tools the agent has access to
tools:
  - name: Order lookup
    type: mcp
    icon: /icons/tools/postgres.svg
    url: https://mcp.example.com/orders/lookup
    description: Retrieves order status, totals, shipment milestones, and recent order events.

# Optional messages this agent receives
receives:
  - id: OrderConfirmed
  - id: OrderCancelled

# Optional messages this agent sends
sends:
  - id: SupportTicketCreated

# Optional data stores the agent reads from
readsFrom:
  - id: OrdersDatabase

# Optional data stores the agent writes to
writesTo:
  - id: SupportCaseNotes

# Optional flows associated with this agent
flows:
  - id: OrderSupportFlow
    version: 1.0.0

# Optional repository details
repository:
  language: TypeScript
  url: https://github.com/example/order-support-agent

# Optional badges, rendered to UI by EventCatalog
badges:
  - content: AI
    backgroundColor: purple
    textColor: purple
    icon: SparklesIcon
---

## Overview

The Order Support Agent helps the support team answer order questions without manually checking every backing service.

<NodeGraph />

Required fields

id

• Type: string

Unique id of the agent. EventCatalog uses this for references and slugs.

Example

---
  id: OrderSupportAgent
---

name

• Type: string

Name of the agent, used to display the name on the UI.

Example

---
  name: Order Support Agent
---

version

• Type: string

Version of the agent.

Example

---
  version: 0.0.1
---

Optional fields

summary

Short summary of the agent, shown on listing and summary pages.

Example

---
  summary: |
    Assists support teams by investigating customer order questions.
---

owners

An array of user or team ids that own the agent.

Example

---
  owners:
    - dboyne
    - order-management
---

model

The model that powers the agent. All fields are optional.

Example

---
  model:
    provider: OpenAI
    name: gpt-4.1-mini
    version: "2025-04-14"
---

Property	Type	Required	Description
provider	string	No	The model provider (e.g. OpenAI, Anthropic, Google).
name	string	No	The model name (e.g. gpt-4.1-mini, claude-3.5-haiku).
version	string	No	The model version or snapshot identifier.

tools

An array of tools the agent has access to. Tools represent MCP servers, APIs, databases, or any other external capability the agent can reach.

Example

---
  tools:
    - name: Order lookup
      type: mcp
      icon: /icons/tools/postgres.svg
      url: https://mcp.example.com/orders/lookup
      description: Retrieves order status, totals, and shipment milestones.
---

Property	Type	Required	Description
name	string	Yes	The name of the tool.
type	string	Yes	The type of tool (e.g. mcp, api, database).
icon	string	No	URL or path to an icon for the tool.
url	string	No	URL where the tool is reachable.
description	string	No	What the tool does.

sends

An array of messages (ids) the agent sends. These can be commands, queries, or events.

Example

---
  sends:
    - id: SupportTicketCreated
      version: 1.0.0
---

receives

An array of messages (ids) the agent receives. These can be commands, queries, or events.

Example

---
  receives:
    - id: OrderConfirmed
    - id: OrderCancelled
      version: 0.0.1
---

writesTo

An array of data stores ids that the agent writes to.

Example

---
  writesTo:
    - id: SupportCaseNotes
      version: 0.0.1
---

readsFrom

An array of data stores ids that the agent reads from.

Example

---
  readsFrom:
    - id: OrdersDatabase
      version: 0.0.1
---

flows

An array of flows ids that are associated with this agent.

Example

---
  flows:
    - id: OrderSupportFlow
      version: 1.0.0
---

repository

Details about the programming language and url for the code that powers the agent.

Example

---
  repository:
    language: TypeScript
    url: https://github.com/example/order-support-agent
---

badges

An array of badges that get rendered on the page.

Example

---
  badges:
    - content: AI
      backgroundColor: purple
      textColor: purple
      icon: SparklesIcon
---

See the Service API badges section for the full list of supported colors and link badge syntax.

visualiser

Turn off the visualiser for this resource. When false, the agent will not be included in the visualiser or its navigation.

Default: true

Example

---
  visualiser: false
---

editUrl

Override the default edit url for the page.

Example

---
  editUrl: https://github.com/example/eventcatalog/edit/main/agents/OrderSupportAgent/index.mdx
---

detailsPanel

Override the default details panel for the page. Use this to show or hide specific areas.

Example

---
  detailsPanel:
    domains:
      visible: false
    messages:
      visible: false
    tools:
      visible: false
    model:
      visible: false
---

Property	Type	Required	Description
domains	object	No	Show/hide the domains section.
messages	object	No	Show/hide the messages section (sends and receives).
versions	object	No	Show/hide the versions section.
repository	object	No	Show/hide the repository section.
owners	object	No	Show/hide the owners section.
changelog	object	No	Show/hide the changelog button.
containers	object	No	Show/hide the containers section.
tools	object	No	Show/hide the tools section.
model	object	No	Show/hide the model section.

attachments

An array of attachments for this resource. See the Service API attachments section for the full schema.