AgentFile Syntax Reference

What is AgentFile?

AgentFile is a declarative DSL for configuring AI agent execution environments, similar to how Dockerfile defines container builds. Each agent in AgentsMesh has an AgentFile that specifies the CLI command, environment variables, configuration options, and build logic needed to launch the agent.

Structure

An AgentFile consists of two types of statements: declarations and build logic.

Declaration Keywords

Declarations define the agent's configuration schema and runtime environment. They are written in UPPERCASE.

AGENT "claude-code"
AGENT "aider --model opus"

EXECUTABLE "claude"

CONFIG model STRING = "sonnet"
CONFIG verbose BOOL = false
CONFIG max_tokens NUMBER = 4096
CONFIG api_key SECRET
CONFIG mode SELECT("fast","balanced","quality") = "balanced"

ENV ANTHROPIC_API_KEY SECRET
ENV DEBUG TEXT OPTIONAL
ENV NODE_ENV = "production"

MODE pty
MODE acp --model opus

CREDENTIAL "my-anthropic-profile"
CREDENTIAL runner_host

PROMPT "Fix the login bug in auth.ts"
PROMPT_POSITION prepend  # prepend | append | none

REPO "my-org/my-repo"
BRANCH "feature/new-auth"
GIT_CREDENTIAL http  # http | ssh | token

MCP ON
MCP ON FORMAT streamable-http
MCP OFF

SKILLS code-review, deploy-helper

SETUP timeout=60 <<SCRIPT
npm install
npm run build
SCRIPT

REMOVE ENV DEBUG
REMOVE SKILLS deploy-helper
REMOVE arg --verbose
REMOVE file /tmp/cache

Build Logic

Build logic statements are lowercase and execute during the AgentFile evaluation phase. They construct CLI arguments, write files, and apply conditional logic.

# Variable assignment
model_flag = "--model " + config.model

# arg — append CLI argument
arg model_flag

# file — write a file
file ".env" "NODE_ENV=production"

# mkdir — create a directory
mkdir sandbox.work_dir + "/output"

# if / else
if config.verbose {
  arg "--verbose"
} else {
  arg "--quiet"
}

# for / in
for server in mcp.servers {
  arg "--mcp-server " + server
}

# when — shorthand conditional
when config.verbose arg "--verbose"

Expressions

AgentFile supports a variety of expression types that can be used in build logic and declarations.

Built-in Variables

These variables are automatically available during AgentFile evaluation and provide access to configuration values and runtime context.

String Escaping

AgentFile strings support standard escape sequences inside double-quoted strings:

\\  →  backslash
\"  →  double quote
\n  →  newline
\t  →  tab

Full Example

Here is a complete AgentFile for Claude Code, showing declarations, configuration, build logic, and setup script:

# Claude Code AgentFile
AGENT "claude-code"
EXECUTABLE "claude"

# Execution mode: PTY terminal
MODE pty

# User-configurable options
CONFIG model STRING = "sonnet"
CONFIG permission_mode SELECT("default","plan","acceptEdits","dontAsk","bypassPermissions") = "bypassPermissions"
CONFIG verbose BOOL = false

# Environment variables
ENV ANTHROPIC_API_KEY SECRET
ENV CLAUDE_CODE_USE_BEDROCK TEXT OPTIONAL

# MCP tools enabled
MCP ON

# Build the CLI arguments
arg "--model " + config.model

if config.permission_mode != "default" and config.permission_mode != "" {
  arg "--permission-mode" config.permission_mode
}

when config.verbose arg "--verbose"

# Inject MCP server configuration
for server in mcp.servers {
  arg "--mcp-config " + server
}

# Setup script runs before the agent starts
SETUP timeout=30 <<INIT
echo "Workspace ready at $(pwd)"
INIT