# Agent frontmatter API Copy as Markdown[View as Markdown](/docs/api/agent-api.md) *** **Added in** `eventcatalog@3.41.0` ## Overview[​](#overview "Direct link to 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. ``` ## Required fields[​](#required-fields "Direct link to Required fields") ### `id`[​](#id "Direct link to id") * Type: `string` Unique id of the agent. EventCatalog uses this for references and slugs. Example ``` --- id: OrderSupportAgent --- ``` ### `name`[​](#name "Direct link to name") * Type: `string` Name of the agent, used to display the name on the UI. Example ``` --- name: Order Support Agent --- ``` ### `version`[​](#version "Direct link to version") * Type: `string` Version of the agent. Example ``` --- version: 0.0.1 --- ``` ## Optional fields[​](#optional-fields "Direct link to Optional fields") ### `summary`[​](#summary "Direct link to summary") Short summary of the agent, shown on listing and summary pages. Example ``` --- summary: | Assists support teams by investigating customer order questions. --- ``` ### `owners`[​](#owners "Direct link to owners") An array of user or team ids that own the agent. Example ``` --- owners: - dboyne - order-management --- ``` ### `model`[​](#model "Direct link to 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`[​](#tools "Direct link to 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`[​](#sends "Direct link to 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`[​](#receives "Direct link to 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`[​](#writesTo "Direct link to writesTo") An array of [data stores](/docs/development/guides/data/introduction.md) ids that the agent writes to. Example ``` --- writesTo: - id: SupportCaseNotes version: 0.0.1 --- ``` ### `readsFrom`[​](#readsFrom "Direct link to readsFrom") An array of [data stores](/docs/development/guides/data/introduction.md) ids that the agent reads from. Example ``` --- readsFrom: - id: OrdersDatabase version: 0.0.1 --- ``` ### `flows`[​](#flows "Direct link to flows") An array of [flows](/docs/development/guides/flows/introduction.md) ids that are associated with this agent. Example ``` --- flows: - id: OrderSupportFlow version: 1.0.0 --- ``` ### `repository`[​](#repository "Direct link to 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`[​](#badges "Direct link to 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](/docs/api/service-api.md#badges) for the full list of supported colors and link badge syntax. ### `visualiser`[​](#visualiser "Direct link to 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`[​](#editUrl "Direct link to editUrl") Override the default edit url for the page. Example ``` --- editUrl: https://github.com/example/eventcatalog/edit/main/agents/OrderSupportAgent/index.mdx --- ``` ### `detailsPanel`[​](#detailsPanel "Direct link to 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`[​](#attachments "Direct link to attachments") An array of attachments for this resource. See the [Service API attachments section](/docs/api/service-api.md#attachments) for the full schema.