Agents reference

View as Markdown

---

This page lists the fields, paths, and routes supported by agents.

Paths

Agents can be created in any agents folder:

/agents/{Agent Name}/index.mdx
/domains/{Domain Name}/agents/{Agent Name}/index.mdx

Versioned agents use:

/agents/{Agent Name}/versioned/{version}/index.mdx

Routes

Route	Description
/docs/agents/{agent-id}/{version}	Agent documentation page.
/visualiser/agents/{agent-id}/{version}	Agent resource diagram.

Required fields

id

• Type: string

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

Example

---
id: customer-support-agent
---

name

• Type: string

Display name of the agent.

Example

---
name: Customer Support Agent
---

version

• Type: string

Version of the agent documentation.

Example

---
version: 1.0.0
---

Optional fields

summary

• Type: string

Short description of what the agent does.

Example

---
summary: Answers customer support questions using catalog and order context.
---

owners

• Type: array

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

Example

---
owners:
  - support-platform
---

model

• Type: object

Model metadata for the agent.

Example

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

tools

• Type: array

Tools the agent can use.

Example

---
tools:
  - name: Order lookup
    type: mcp
    url: https://mcp.example.com/orders
    description: Retrieves order status and recent order events.
---

sends

• Type: array

Messages the agent sends.

Example

---
sends:
  - id: SupportCaseCreated
    version: 1.0.0
---

receives

• Type: array

Messages the agent receives.

Example

---
receives:
  - id: CustomerQuestionAsked
    version: 1.0.0
---

readsFrom

• Type: array

Data stores the agent reads from.

Example

---
readsFrom:
  - id: support-knowledge-base
    version: 1.0.0
---

writesTo

• Type: array

Data stores the agent writes to.

Example

---
writesTo:
  - id: support-case-store
    version: 1.0.0
---

badges

• Type: array

Badges rendered on the agent page.

Example

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

repository

• Type: object

Repository metadata for the agent.

Example

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

Model fields

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

Tool fields

---
tools:
  - name: Order lookup
    type: mcp
    url: https://mcp.example.com/orders
    description: Retrieves order status and recent order events.
---

Custom properties

You can add organization-specific metadata to this resource using frontmatter fields prefixed with x-. Learn how to define, render, and reference them in Custom properties on resources.