Skip to main content

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​

RouteDescription
/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.
---