Skip to main content

Agent Specifications

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

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