Agents
Agent (AI Agent / Digital Worker) is the unit that does the work in Markus. The platform formula:
Agent = LLM + Harness + Learning Loop— an executable worker driven by an LLM, wrapped in a runtime (tools / memory / attention) plus a learning loop. This page explains it end to end: what an Agent is, how an Agent Package is built (manifest / ROLE.md / skill binding / avatar), and the rules for publishing to the Hub. ← Back to Assets · 中文原版
1. Concept Overview
| Concept | Description |
|---|---|
| Agent | An AI agent: a self-identity ROLE.md + a set of tools + memory and heartbeat, assignable to do work |
| Agent Package | A reusable, Hub-publishable, self-contained directory artifact defining the Agent’s identity / capabilities / constraints / visual assets |
| Manifest (agent.json) | Package metadata: name, version, dependencies, LLM config, role |
| ROLE.md | The Agent’s identity document = system prompt, defining “who it is, how it works” |
| Skill binding | Declares the skills this Agent depends on via dependencies.skills |
Key distinction: creating an Agent package (writing into builder-artifacts — just a reusable artifact) ≠ installing / hiring (deploying into the organization, consuming resources, joining a team). Never install automatically — only when the user explicitly says install / deploy / hire.
2. Artifact Directory
The system only recognizes this one path — the Builder page, the install system, and deliverable detection all depend on it:
~/.markus/builder-artifacts/agents/{agent-name}/ ← {name} must be a valid slug
├── agent.json # config (manifest; write with file_write as JSON)
├── README.md # public description (Hub / Builder display, REQUIRED)
├── ROLE.md # identity & system prompt (REQUIRED — the identity itself)
├── HEARTBEAT.md # periodic self-check checklist (RECOMMENDED)
├── POLICIES.md # constraints & guardrails (optional)
├── CONTEXT.md # domain context & reference material (optional)
└── images/
└── avatar.jpg # Agent avatar (digital employee portrait)
Do not write to ~/.markus/shared/, the current working directory, or anywhere else — only builder-artifacts/agents/ is recognized by the system. After installation, files are deployed to ~/.markus/agents/{agentId}/role/, where ROLE.md becomes the Agent’s system prompt — it is the Agent’s identity, not an override of a template.
3. Two-Step Workflow
Manifest first, then content files. This rule applies to every mode (chat / task / A2A): JSON code blocks in replies do not create files automatically, and never inline file content into JSON.
file_write("~/.markus/builder-artifacts/agents/{name}/agent.json", ...)— write the manifest (metadata only).file_writethe content files in order: README.md → ROLE.md → HEARTBEAT.md → POLICIES.md → CONTEXT.md → images/avatar.jpg.
4. Manifest (agent.json) Fields
{
"type": "agent",
"name": "code-reviewer", // slug, kebab-case English letters/numbers/hyphens required
"displayName": "Code Reviewer", // human-readable name (any language)
"version": "1.0.0",
"description": "What this agent does",
"author": "",
"category": "development", // development | devops | management | productivity | general | marketing | engineering | product-management
"tags": ["review", "code-quality"],
"icon": "images/avatar.jpg", // emoji or relative image path
"thumbnail": "images/avatar.jpg",
"screenshots": ["images/avatar.jpg"],
"license": "MIT",
"originalSource": "https://github.com/...",
"dependencies": { "skills": ["coding-tools"], "env": ["git", "node"] },
"agent": { "agentRole": "worker", "llmProvider": "anthropic", "llmModel": "", "temperature": 0.7 }
}
Package Name (Slug) — Hard Rule
name is the package slug: simultaneously the directory name, the Hub URL segment (/@user/{slug}), and the share/publish ID. Invalid slugs are rejected on write / save / share:
- English kebab-case only: lowercase
a-z, digits0-9, hyphens-; 2–64 characters, must start with a letter. - Not allowed: Chinese, spaces, underscores, uppercase, emoji, empty.
- Put the human-readable title (may be Chinese) in
displayName, never inname. When the user only gives a Chinese name, invent a semantically fitting English kebab slug and keep the original name indisplayName.
| User language | name (slug) | displayName |
|---|---|---|
| 论文导师 (Chinese) | paper-mentor | 论文导师 |
| ”Code Reviewer” (English) | code-reviewer | Code Reviewer |
Field Quick Reference
| Field | Description | Notes |
|---|---|---|
category | Category | Limitation: restricted to the field enum |
dependencies.skills | Array of skill IDs this agent depends on | Assign proactively; don’t leave empty |
dependencies.env | Required CLI tools | e.g. ["git", "node"] |
agent.agentRole | worker or manager | manager coordinates / assigns / reviews |
agent.llmProvider / llmModel / temperature | LLM config | Empty = system default; temperature: 0.7 general, 0.3–0.5 precise, 0.8–1.0 creative |
roleName | Not needed | The Agent’s identity is fully defined by ROLE.md; unless you want to inherit a built-in role template’s default tools (rare), don’t add it |
⚠️ Manifest validation: all top-level field types must be correct (
authoris a string, not an object;tagsis a string array;versionis semver;descriptionis a string). The system validates on write and rejects invalid manifests.
5. ROLE.md Is the Identity (+ HEARTBEAT / POLICIES)
Once installed, ROLE.md becomes the Agent’s system prompt — the source of its distinctiveness — requiring at least 5 substantive paragraphs; a paragraph of boilerplate is useless. Cover: identity (who I am / personality / expertise), core responsibilities, a workflow that works with platform capabilities (when to spawn_subagent to split subtasks, background_exec for long commands, shell_execute for git/gh, web_search / web_fetch for research, deliverable_create for outputs, memory_save for persistent memory), output standards and quality gates, and domain knowledge. For coding Agents: workspace isolation (git worktree), TDD, review-then-merge; for review Agents: the review → merge flow with git merge / gh pr create|merge.
Companion files:
- README.md (REQUIRED): the public-facing display for Hub/Builder — 2–4 paragraphs: what it does, what problem it solves, core capabilities, usage scenarios, required environment.
- HEARTBEAT.md (RECOMMENDED): defines what to actively patrol roughly every 30 minutes (check the mailbox for urgent items, recheck assigned tasks, scan team announcements, role-specific patrol items). Without it the Agent is only passive — it never proactively monitors its environment.
- POLICIES.md: safety guardrails — what not to do, tool usage rules, quality gates. Safety comes from POLICIES constraints, not from removing tools — all Agents can use all built-in tools by default.
6. Skill Binding (dependencies.skills)
An Agent binds skills through dependencies.skills:
"dependencies": { "skills": ["coding-tools", "chrome-devtools"] }
- Skills are reusable capability packages (see Skills); after installation the Agent loads them progressively via
discover_tools— full instructions are not stuffed into the system prompt at spawn time. - Don’t invent skill IDs: only use skills that actually exist in the dynamic context; when a skill is available, don’t leave it empty.
7. Visual Assets (avatar)
An Agent avatar is a digital employee portrait — realistic human style, not an abstract logo/illustration. Users should treat Agents as team members, not mascots. The subject must always be a person: match the character’s personality (PM = organized/strategic, creator = creative/approachable), colors that fit the role (blue = analytical, orange = creative, green = growth), clean professional background.
| Property | Value |
|---|---|
| Resolution | 512×512 (square) |
| Format | JPEG |
| Max size | ≤50KB |
| Compression | Python Pillow resize + save |
Example prompt:
Professional headshot of a friendly male engineering lead in business casual, warm blue tones, clean background, realistic digital portrait. Always compress (generate_imageoften outputs 400KB+ → 512×512/≤50KB, saving ~96%). Images go in theimages/subdirectory.
Local vs Hub field mapping: local artifacts use relative paths thumbnail / screenshots; when published to the Hub they map to thumbnailUrl / images ({url,alt,order}[]). Publishing details: Markus Hub →.
8. Create ≠ Install (Red Line)
Creating an artifact ≠ installing/deploying. Creating only writes files to builder-artifacts/; installing deploys a real Agent into the active organization (consuming resources, joining a team). Never install automatically unless the user explicitly says “install” / “deploy” / “hire” — then use package_install / hub_install. After creating: tell the user it was created and saved, that visual assets are included, that it can be installed (Builder page or package_install), and that it can be iterated on (just update the files).
9. Build Rules Quick Reference
- Don’t invent Skill IDs — only use values present in the dynamic context; don’t default
skillsto[]. - Don’t stuff file content into JSON — always
file_writereal files. - Don’t write to
~/.markus/shared/or the working directory — always~/.markus/builder-artifacts/agents/{name}/. namemust be a valid English kebab-case slug; top-level field types must be correct (validated on write).- Avatars must be realistic portraits / digital employee portraits; always compress images (≤50KB); images go in the
images/subdirectory. - ROLE.md: at least 5 substantive paragraphs; temperature: 0.7 general, 0.3–0.5 precise, 0.8–1.0 creative.
10. Next Steps
- Orchestrate multiple Agents into a team → Teams.
- Give Agents reusable capabilities → Skills.
- Publish and ship the package to the Hub marketplace → Markus Hub.