# Agents reference

Copy as Markdown[View as Markdown](/docs/development/guides/resources/agents/reference.md)

***

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

## Paths[​](#paths "Direct link to 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[​](#routes "Direct link to Routes")

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

## 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 URLs and resource references.

Example

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

### `name`[​](#name "Direct link to name")

* Type: `string`

Display name of the agent.

Example

```
---
name: Customer Support Agent
---
```

### `version`[​](#version "Direct link to version")

* Type: `string`

Version of the agent documentation.

Example

```
---
version: 1.0.0
---
```

## Optional fields[​](#optional-fields "Direct link to Optional fields")

### `summary`[​](#summary "Direct link to summary")

* Type: `string`

Short description of what the agent does.

Example

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

### `owners`[​](#owners "Direct link to owners")

* Type: `array`

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

Example

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

### `model`[​](#model "Direct link to model")

* Type: `object`

Model metadata for the agent.

Example

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

### `tools`[​](#tools "Direct link to 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`[​](#sends "Direct link to sends")

* Type: `array`

Messages the agent sends.

Example

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

### `receives`[​](#receives "Direct link to receives")

* Type: `array`

Messages the agent receives.

Example

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

### `readsFrom`[​](#readsFrom "Direct link to readsFrom")

* Type: `array`

Data stores the agent reads from.

Example

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

### `writesTo`[​](#writesTo "Direct link to writesTo")

* Type: `array`

Data stores the agent writes to.

Example

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

### `badges`[​](#badges "Direct link to badges")

* Type: `array`

Badges rendered on the agent page.

Example

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

### `repository`[​](#repository "Direct link to repository")

* Type: `object`

Repository metadata for the agent.

Example

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

## Model fields[​](#model-fields "Direct link to Model fields")

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

## Tool fields[​](#tool-fields "Direct link to Tool fields")

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