> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.astropods.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.astropods.com/_mcp/server. # Agent Card When you publish an agent to the registry, other users see it on browse pages, search results, and detail pages. An **agent card** (`AGENT.md`) controls what they see: a description, tags for filtering, author attribution, capability badges, and integration icons. Create an `AGENT.md` file at the root of your project (next to `astropods.yml`). It's published automatically when you run `ast blueprint push`. ## Quick example ```yaml AGENT.md --- description: "GitHub Issue Analyzer — ingests GitHub issues into a Neo4j knowledge graph" tags: - analytics - knowledge-graph authors: - name: Jane Doe account: janedoe - name: Bob Smith repository: "github:acme/github-issue-analyzer" capabilities: - Analyzes GitHub issues and extracts patterns - Builds and maintains a Neo4j knowledge graph - Answers natural-language queries about issue history integrations: - Jira - My Custom Webhook --- # GitHub Issue Analyzer This agent ingests GitHub issues into a Neo4j knowledge graph and provides natural-language querying over the resulting data. ## How It Works 1. Connect your GitHub repository via the `GITHUB_TOKEN` input. 2. The agent polls for new issues on a configurable schedule. 3. Each issue is analyzed using an LLM to extract entities and relationships. 4. Results are stored in Neo4j and queryable via the agent's chat interface. ## Limitations - Only processes issue bodies and comments; PR reviews are not yet supported. - Large repositories (>10k issues) may require extended initial ingestion time. ``` ## What's in an agent card An agent card has two parts: 1. **Frontmatter**: A YAML block between `---` delimiters at the top of the file. Powers structured UI elements like tags, author links, and integration icons. 2. **Body**: Free-form Markdown after the frontmatter. Rendered as the main content on your agent's detail page. Both parts are optional; even a file with just a description in the frontmatter improves discoverability. For the full format specification, see the [Agent Card Spec](/agent-card-spec). *** ## Frontmatter fields All fields are optional. ### `description` The most important field for discoverability. This short summary appears on cards, search results, and the detail page sidebar. Keep it under 200 characters. ```yaml --- description: "Slack bot that summarizes daily standups into action items" --- ``` If no description is provided, the agent name is used as a fallback. The `description` field replaces the deprecated `meta.description` in `astropods.yml`. If you previously set a description there, move it to your agent card. ### `tags` Category labels that help users find your agent when browsing or filtering. Each tag must be lowercase, using only letters, numbers, and hyphens. Maximum 10 tags. See [normalization rules](/agent-card-spec#4-normalization) for how tags are processed. ```yaml --- tags: - devops - monitoring - slack --- ``` The `tags` field replaces the deprecated `meta.tags` in `astropods.yml`. Move any existing tags to your agent card. ### `authors` A list of people or organizations who built the agent. Each entry requires a `name` and optionally an `account` that links to a platform profile. ```yaml --- authors: - name: Alice Chen account: alicechen - name: Acme Corp account: acme - name: External Contributor --- ``` | Field | Type | Required | Description | | --------- | ------ | -------- | ----------------------------------------------------------------------- | | `name` | string | Yes | Display name of the author. | | `account` | string | No | Platform account handle. When present, links to that account's profile. | ### `capabilities` Short verb phrases describing what the agent can do. These appear as badges on the detail page and help users understand the agent's functionality at a glance. Keep each under 100 characters. ```yaml --- capabilities: - Monitors pull requests for security vulnerabilities - Generates weekly summary reports - Responds to Slack commands in real time --- ``` ### `repository` A pointer to the agent's source-code repository. Accepts a shorthand string or an object. A bare `user/repo` is treated as GitHub. You can also prefix with `github:`, `gitlab:`, `bitbucket:`, or `gist:`. ```yaml --- repository: "github:acme/my-agent" --- ``` For the full specification including the object form, see the [Agent Card Spec](/agent-card-spec#25-repository). ### `integrations` Third-party services your agent connects to. Known integrations are displayed with brand icons; unknown ones show a generic icon with the name as a label. ```yaml --- integrations: - Slack - Jira - My Custom API --- ``` Matching is case-insensitive: `slack`, `Slack`, and `SLACK` all resolve the same way. Integrations declared in your `astropods.yml` (via the `integrations` section with a `provider` field) are automatically derived and displayed on your agent's detail page. Use the agent card to declare additional integrations that aren't in the spec, such as services your agent calls directly using user-supplied credentials. Each integration string is matched against a list of known integrations (Slack, GitHub, Jira, Notion, Linear, Google Drive, Discord, Microsoft Teams, and many more). Known integrations are displayed with brand icons. Any string that doesn't match a known integration is displayed with a generic icon and the original text as a label. For the full list, see [Known Integrations](/known-integrations). *** ## Body The Markdown body below the frontmatter is rendered as the main content on your agent's detail page. There's no required structure, but consider covering: * **Overview**: What the agent does and why it exists. * **Usage**: How to interact with the agent (APIs, chat, scheduled tasks, etc.). * **Limitations**: Known constraints or scope boundaries. * **Examples**: Sample interactions or outputs. A well-written body helps users evaluate whether your agent fits their needs before they deploy it. *** ## Publishing your agent card Your agent card is published automatically with `ast blueprint push` with no extra flags needed. The CLI reads `AGENT.md` from your project root and includes it in the registration payload. ```bash ast blueprint push ``` If you update your `AGENT.md`, push again and the changes appear immediately on your agent's detail page. ## Previewing your agent card After pushing, view the rendered card from the CLI: ```bash ast blueprint get --card ``` This prints the agent description, tags, authors, capabilities, and integrations as they appear on the catalog page. *** ## Migration from meta fields If your `astropods.yml` uses the deprecated `meta.description` or `meta.tags` fields, move them to your agent card: **Before** (`astropods.yml`): ```yaml spec: blueprint/v1 name: my-agent meta: description: "My agent description" tags: - analytics - slack visibility: public ``` **After** (`AGENT.md` + updated `astropods.yml`): ```yaml AGENT.md --- description: "My agent description" tags: - analytics - slack --- ``` ```yaml astropods.yml spec: blueprint/v1 name: my-agent meta: visibility: public ``` Existing agents without an `AGENT.md` continue to work; the `meta.description` and `meta.tags` fields are still read as a fallback. This may change in the future. See the [Agent Card Spec](/agent-card-spec) for full details on field behavior and normalization.