Skip to main content

Agent Specifications

Agent specifications define runtime behavior, capabilities, and UX defaults for individual agents.

An agent spec is mostly references: to the skills it has, the tools and MCP servers it can reach, the model it runs on, where its memory lives, what it is judged by. Each of those is its own catalogue, and each has a page below.

What an agent is made of​

Overview​

Agents are stored flat under agentspecs/agents/ and include explicit version.

Use versioned references in linked fields:

skills:
  - github:0.0.1

mcp_servers:
  - tavily:0.0.1

Generated catalogs expose both id and id:version aliases.

Required Fields​

id (string)​

Unique identifier (kebab-case).

version (string)​

Spec version (currently 0.0.1).

name (string)​

Display name shown in the UI

description (string)​

Agent capabilities description (1-2 sentences)

Optional Fields​

tags (list of strings)​

Categorization tags for filtering and search

tags:
  - finance
  - visualization
  - charts

enabled (boolean)​

Whether agent is active (default: true)

mcp_servers (list of strings)​

MCP server references. Prefer id:version format.

mcp_servers:
  - alphavantage:0.0.1
  - chart:0.0.1
  - github:0.0.1

skills (list of strings)​

Skill references. Prefer id:version format.

skills:
  - github:0.0.1
  - events:0.0.1

environment_name (string)​

Runtime environment name (default: "ai-agents")

model (string)​

AI model ID to use for this agent. References a model spec in models/ directory by its id field. If omitted, the system default model is used.

model: "bedrock:us.anthropic.claude-sonnet-4-5-20250929-v1:0"
model: "openai:gpt-4.1"
model: "anthropic:claude-opus-4-20250514"

icon (string)​

UI icon identifier (e.g., "trending-up", "code", "database")

emoji (string)​

UI emoji identifier (e.g., "📈", "💻", "🔍")

color (string)​

Hex color code for UI theming

color: "#3B82F6"  # Blue
color: "#10B981"  # Green  
color: "#F59E0B"  # Amber
color: "#6366F1"  # Indigo

suggestions (list of strings)​

Chat examples to show users what the agent can do (3-5 recommended)

suggestions:
  - Show me the stock price history for AAPL
  - Create a chart comparing MSFT and GOOGL
  - Analyze the trading volume trends for Tesla

welcome_message (string)​

Greeting message shown when agent starts

welcome_message: >
  Welcome! I'm the Financial Visualization Agent. I can help you analyze
  stock market data, track financial instruments, and create charts to
  visualize market trends.

system_prompt (string)​

Base system prompt for the agent. Defines the agent's role and capabilities.

system_prompt: >
  You are a financial market analyst with access to Alpha Vantage market data
  and chart generation tools. You can fetch stock prices, analyze trading volumes,
  create visualizations, and track market trends.

system_prompt_codemode_addons (string)​

Additional instructions for Code Mode execution environment. This field provides guidance on how to use the 4 core Codemode tools (list_servers, search_tools, get_tool_details, execute_code).

system_prompt_codemode_addons: >
  ## IMPORTANT: Be Honest About Your Capabilities
  NEVER claim to have tools or capabilities you haven't verified.

  ## Core Codemode Tools
  Use these 4 tools to accomplish any task:
  1. **list_servers** - List available MCP servers
  2. **search_tools** - Progressive tool discovery by natural language query
  3. **get_tool_details** - Get full tool schema and documentation
  4. **execute_code** - Run Python code that composes multiple tools

  ## Recommended Workflow
  1. **Discover**: Use list_servers and search_tools to find relevant tools
  2. **Understand**: Use get_tool_details to check parameters
  3. **Execute**: Use execute_code to perform multi-step tasks

welcome_notebook (string)​

Jupyter notebook path to show on agent creation (optional)

welcome_document (string)​

Lexical document path to show on agent creation (optional)

Complete Example​

id: data-acquisition
version: 0.0.1
name: Data Acquisition Agent
description: Acquire and manage data from external and local sources.

enabled: true
model: "bedrock:us.anthropic.claude-sonnet-4-5-20250929-v1:0"

mcp_servers:
  - kaggle:0.0.1
  - filesystem:0.0.1
  - tavily:0.0.1

skills:
  - github:0.0.1
  - events:0.0.1

environment_name: ai-agents-env
icon: database
emoji: "📊"
color: "#3B82F6"

Full Field Coverage​

Commonly used fields:

  • enabled
  • model
  • sandbox_variant
  • memory
  • mcp_servers (use id:version refs)
  • skills (use id:version refs)
  • tools (use id:version refs)
  • environment_name
  • tags
  • icon, emoji, color
  • suggestions
  • welcome_message, welcome_notebook, welcome_document
  • system_prompt, system_prompt_codemode_addons

Advanced workflow fields:

  • goal
  • protocol
  • ui_extension
  • trigger
  • model_configuration
  • mcp_server_tools
  • guardrails
  • evals
  • codemode
  • output
  • advanced
  • authorization_policy
  • notifications

Catalog Key Convention​

Generated catalogs are keyed by unversioned id only (e.g. crawler). The getAgentSpec accessor accepts both bare ids and versioned refs (crawler:0.0.1), stripping the version suffix automatically. Iterating catalog values returns each spec exactly once.

Best Practices​

  1. ID Format: Use kebab-case (financial-viz, not financial_viz)
  2. Folder Selection: Choose the most appropriate category folder
  3. Description: 1-2 sentences, present tense, focus on capabilities
  4. Tags: 2-5 relevant keywords for categorization
  5. Suggestions: Provide 3-5 concrete, actionable examples
  6. Colors: Use hex codes consistently based on agent type:
    • Blue (#3B82F6): Data and information
    • Green (#10B981): Web and networking
    • Indigo (#6366F1): Development and code
    • Amber (#F59E0B): Finance and analytics
    • Pink (#EC4899): Communication and workflow
  7. System Prompts: Keep base prompt general, use addons for execution-specific guidance
  8. MCP References: Only reference MCP servers that exist in mcp-servers/ directory