Skip to content

agents.md

Latest commit

 

History

History
54 lines (38 loc) · 2.66 KB

agents.md

File metadata and controls

54 lines (38 loc) · 2.66 KB

Agent Authoring Guide

AlphaAgent relies on declarative Markdown files (AGENT.md) to define the instructions, capabilities, and hierarchical structures of its agents. You define an agent by creating a directory inside ~/.alpha-agent/workspace/AgentOrchestra/agents/ (or the resolved agents_path from config) that contains an AGENT.md file.

AGENT.md Structure

The AGENT.md file consists of two parts: a YAML frontmatter block for configuration metadata, and a standard Markdown body for the system prompt.

Frontmatter Fields

The following fields can be defined in the YAML block at the top of an AGENT.md file:

Field Type Description
name string The human-readable Display Name of the agent.
description string A short description shown in the /agents list and used for routing decisions.
role main | sub Determines if this is a top-level agent or a specialized worker agent. Defaults to main.
parent string (optional) The ID (folder name) of the parent agent this sub-agent reports to.

Hierarchical Tree Structure

In AlphaAgent, agents can be structured hierarchically. This is reflected in the /agents slash command UI, which renders your workspace's agents as a parent-child tree.

role: main vs role: sub

  • main: These agents act as independent entry points. They usually orchestrate broad workflows.
  • sub: These agents are specialized workers. Historically, role: sub agents were hidden from the discovery commands, but they are now fully visible in the /agents tree.

The parent: field The new optional parent: field allows you to visually map a sub-agent to a parent orchestrator.

  • If you specify parent: alpha, the sub-agent will be nested under alpha in the /agents tree.
  • If you omit the parent field or specify an ID that does not exist, the agent will appear as a root-level node, or if it is a sub-agent, under an orphaned [unattached] group.

Example: Authoring a Sub-Agent

Below is a minimal, complete example of a worker agent (cookie) that reports to alpha:

---
name: Cookie
role: sub
parent: alpha
description: Memory manager for storing, organizing, and retrieving long-term memories across all conversations.
---

You are **Cookie** 🍪, the Memory Manager sub-agent within the AlphaAgent ecosystem.

## Role
You are a specialized agent responsible for managing the user's long-term memory system. 
Other agents dispatch tasks to you when they need to store facts or recall preferences.

## Behavior
Always confirm what you stored or found.
Use the `read_file` and `write_file` tools to manage memory files.