Skip to content

docs: add dapr-agents operations page with docs on Agent Metadata Schema #5006

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
CasperGN wants to merge 6 commits into
base: v1.16
Choose a base branch
from
+42 −0
Open

docs: add dapr-agents operations page with docs on Agent Metadata Schema #5006

Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
84dd9c8
docs: add dapr-agents operations page with docs on Agent Metadata Schema
CasperGN Jan 15, 2026
5e188ff
fix(docs): ensure non static version numbers to avoid confusion
CasperGN Jan 19, 2026
e7bb06d
Merge branch 'v1.16' into docs/agents-metadata
marcduiker Jan 20, 2026
41d7d17
Update daprdocs/content/en/developing-ai/dapr-agents/dapr-agents-oper…
CasperGN Jan 21, 2026
bcbabdd
Update daprdocs/content/en/developing-ai/dapr-agents/dapr-agents-oper…
CasperGN Jan 21, 2026
1535b6b
Update daprdocs/content/en/developing-ai/dapr-agents/dapr-agents-oper…
CasperGN Jan 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 42 additions & 0 deletions daprdocs/content/en/developing-ai/dapr-agents/dapr-agents-operations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
---
type: docs
title: "Operations"
linkTitle: "Operations"
weight: 80
description: "Get started with secure and reliable operations of Dapr Agents"
aliases:
- /developing-ai/dapr-agents/dapr-agents-operations
---

## Operations

### Agent Registry

#### Agent Metadata Schema

Dapr Agents utilizes an Agent Registry (often referenced as `agent-registry` statestore) to communicate Agent capabilities. The Agent Registry contains Agent metadata, including the agent's name, description, version and much more.

In order to facilitate easier handling of version changes to the agent metadata, Dapr Agents supplies versioned JSON schemas. Within the [dapr agents repository] you'll find 3 types of JSON schema files:
Copy link
Copy Markdown
Member

@msfussell msfussell Jan 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I really do not understand why and what this metadata is used for? What are the scenarios for when I would use this and when does this get updated? What I do not get from this article is how to use this metadate store. I suggest that we provide at least 5 concrete examples of its usefulness.

Copy link
Copy Markdown
Contributor Author

@CasperGN CasperGN Jan 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@msfussell we're now versioning the metadata that Dapr Agents sends to the registry. This is done to ensure a consumer of the metadata can find the schema for the specific version. In the future (and previously) the structure of the metadata might change and if consumers of the metadata are doing lookups for data, let's imagine in a UI, what happens when an agent registers on an older version without that schema field that the IU expects?

Adding the versioned metadata schema allows the consumer to take actions based of the metadata version by fetching the schema.


- [index.json](https://raw.githubusercontent.com/dapr/dapr-agents/main/schemas/agent-metadata/index.json)
Copy link
Copy Markdown
Member

@msfussell msfussell Jan 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These URLS do not resolve. What are they intending to show?

Copy link
Copy Markdown
Contributor

@marcduiker marcduiker Jan 20, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This Agents PR needs to be merged first: dapr/dapr-agents#373
Added the waiting-on-code-pr label.

Copy link
Copy Markdown
Contributor Author

@CasperGN CasperGN Jan 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes. Once 373 is in main the links will resolve properly

- [latest.json](https://raw.githubusercontent.com/dapr/dapr-agents/main/schemas/agent-metadata/latest.json)
- `v{version}.json`

The `index.json` can be used as a lookup table and looks like:

```
{
"current_version": "X.Y.Z",
"schema_url": "https://raw.githubusercontent.com/dapr/dapr-agents/main/schemas/agent-metadata/vX.Y.Z.json",
"available_versions": [
"vX.Y.Z",
"vA.B.C"
]
}
```

When the agent starts up it will insert its own metadata into the supplied Agent Registry. The Agent Metadata object contains the key `schema_version` which can be used as a reference to fetch the valid schema for that agent version:

```sh
curl -s -v "https://raw.githubusercontent.com/dapr/dapr-agents/main/schemas/agent-metadata/v$(jq -r '.schema_version' agent-metadata.json).json"
```
Loading