agentx
← Back to docs

agent.yaml Reference

Complete reference for the agent manifest file format.

Required Fields

name

The agent name. Must be lowercase alphanumeric with hyphens, 1-100 characters.

name: gmail-agent

version

Semantic version string (semver).

version: 1.2.0

description

Short description of the agent, 1-500 characters.

description: AI email assistant for Gmail

author

Author scope, must start with @.

author: "@agentx"

Optional Fields

license

License identifier. Defaults to MIT.

license: MIT

tags

Array of searchable tags, maximum 10.

tags:
  - email
  - gmail
  - productivity

category

Agent category. Valid values:

  • productivity
  • devtools
  • communication
  • data
  • writing
  • research
  • automation
  • security
  • monitoring
  • other
category: productivity

requires

System requirements for the agent.

requires:
  claude_cli: ">=1.0.0"
  node: ">=18.0.0"
  os:
    - darwin
    - linux

mcp_servers

MCP server declarations. Each server specifies a command, args, and optional environment variables.

mcp_servers:
  gmail:
    command: npx
    args: ["-y", "@anthropic/mcp-server-gmail"]
    env:
      GMAIL_TOKEN: "${secrets.GMAIL_TOKEN}"
  filesystem:
    command: npx
    args: ["-y", "@anthropic/mcp-server-filesystem", "/home/user/documents"]

Environment variables can reference secrets using ${secrets.KEY} syntax.

secrets

Secret declarations that the agent requires.

secrets:
  - name: GMAIL_TOKEN
    description: Gmail API OAuth token
    required: true
  - name: BACKUP_EMAIL
    description: Optional backup email address
    required: false

permissions

Permission declarations that inform users of the agent's capabilities.

permissions:
  filesystem: true
  network: true
  execute_commands: false

config

Configuration options that users can customize. Values are injected into the system prompt using {{config.key}} syntax.

config:
  - name: language
    description: Preferred response language
    default: English
  - name: tone
    description: Response tone
    default: professional

pre_run

Optional array of commands to execute before the Claude CLI spawns. Maximum 5 entries. Use this to start dependencies like bridges or local servers that the agent's MCP server needs.

pre_run:
  - command: whatsapp-bridge
    background: true
  - command: setup-db
    args: ["--migrate"]

Each entry has the following fields:

| Field | Type | Required | Description |

|-------|------|----------|-------------|

| command | string | Yes | The command to run. Must be on $PATH. |

| args | string[] | No | Arguments to pass to the command. |

| background | boolean | No | If true, the process is spawned detached (fire-and-forget). If false or omitted, the hook blocks and must exit 0 before the agent starts. |

schedule

Optional array of cron-based schedule entries. Maximum 10 entries per agent. When a user runs agentx schedule start <agent>, a background daemon executes the agent at the specified times.

schedule:
  - name: "Daily standup"
    cron: "0 9 * * 1-5"
    prompt: "Post the daily standup summary to #engineering"
  - name: "Weekly report"
    cron: "0 17 * * 5"
    prompt: "Generate and post the weekly activity summary"

Each entry has the following fields:

| Field | Type | Required | Description |

|-------|------|----------|-------------|

| name | string | No | Human-readable label. Defaults to the cron expression if omitted. |

| cron | string | Yes | Standard 5-field cron expression (minute hour day-of-month month day-of-week). |

| prompt | string | Yes | The prompt sent to the agent when the schedule fires. 1-2000 characters. |

examples

Example prompts that demonstrate agent usage.

examples:
  - prompt: "summarize unread emails from today"
  - prompt: "draft a reply to John about the deadline"
  - prompt: "find all emails from acme.com in the last week"

Full Example

name: gmail-agent
version: 1.0.0
description: AI email assistant for Gmail with search, summarize, and draft capabilities
author: "@agentx"
license: MIT
category: productivity
tags:
  - email
  - gmail
  - productivity

requires:
  claude_cli: ">=1.0.0"
  node: ">=18.0.0"

pre_run:
  - command: gmail-bridge
    background: true

mcp_servers:
  gmail:
    command: npx
    args: ["-y", "@anthropic/mcp-server-gmail"]
    env:
      GMAIL_TOKEN: "${secrets.GMAIL_TOKEN}"

secrets:
  - name: GMAIL_TOKEN
    description: Gmail API OAuth token
    required: true

permissions:
  filesystem: false
  network: true
  execute_commands: false

config:
  - name: language
    description: Preferred response language
    default: English

schedule:
  - name: "Morning digest"
    cron: "0 8 * * 1-5"
    prompt: "Summarize unread emails from the last 24 hours"

examples:
  - prompt: "summarize unread emails from today"
  - prompt: "draft a reply to John about the deadline"
  - prompt: "find all emails from acme.com in the last week"