agent-config-validator

Validate AgentConfig definitions for the Agent Framework. Use when creating or modifying agent configurations to ensure correct structure, valid tool references, and proper sub-agent composition. Validates TypeScript interfaces and Python Pydantic models.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

The Agent Config Validator is a specialized developer tool designed to ensure the structural integrity and functional correctness of Agent Framework configurations. It provides automated validation for TypeScript interfaces and Python Pydantic models, helping developers identify missing fields, invalid tool references, and improper sub-agent hierarchies before deployment to prevent runtime orchestration failures.

Use Cases

  • Validating LLM agent definitions to ensure mandatory system prompts, model configurations, and descriptions are correctly set for orchestrator routing.
  • Verifying complex multi-agent workflows (sequential, parallel, or loop) to detect circular dependencies and ensure proper state passing through output keys.
  • Auditing tool references within agent configurations to guarantee that all referenced MCP tool IDs exist and are accessible in the registry.
  • Integrating automated configuration checks into CI/CD pipelines using the provided Python and TypeScript validation commands to maintain high-quality agentic codebases.
nameagent-config-validator
descriptionValidate AgentConfig definitions for the Agent Framework. Use when creating or modifying agent configurations to ensure correct structure, valid tool references, and proper sub-agent composition. Validates TypeScript interfaces and Python Pydantic models.
allowed-toolsRead, Grep, Glob

Agent Configuration Validation

Validates AgentConfig definitions against the Agent Framework schema.

AgentConfig Schema

interface ModelConfig {
  provider: 'gemini' | 'openai' | 'anthropic' | 'ollama' | 'custom';
  model: string;           // e.g., "gpt-4o", "claude-3-haiku", "llama3.2"
  baseUrl?: string;        // For custom/Ollama endpoints
  apiKeyEnvVar?: string;   // Environment variable name for API key
}

interface AgentConfig {
  id: string;                              // Required: unique identifier
  name: string;                            // Required: display name
  type: 'llm' | 'sequential' | 'parallel' | 'loop' | 'custom';  // Required
  modelConfig: ModelConfig;                // Required for type='llm'
  description: string;                     // Required: for orchestrator routing
  instruction: string;                     // Required: system prompt
  tools: string[];                         // MCP tool IDs
  subAgents: string[];                     // Sub-agent IDs
  outputKey?: string;                      // For state passing
  maxIterations?: number;                  // For LoopAgent (default: 3)
  stateSchema?: Record<string, any>;       // Optional state definition
  createdAt: Date;
  isActive: boolean;
}

Validation Rules

Required Fields

Field Type Condition
id string Always required, must be unique
name string Always required
type enum Must be one of: 'llm', 'sequential', 'parallel', 'loop', 'custom'
description string Always required (used for routing)
instruction string Required for 'llm' type
modelConfig object Required for 'llm' type

Type-Specific Rules

LLM Agent

  • Must have modelConfig with valid provider and model
  • Must have instruction (system prompt)
  • outputKey recommended for state passing

Sequential Agent

  • Must have at least 2 agents in subAgents
  • Order matters (first to last execution)

Parallel Agent

  • Must have at least 2 agents in subAgents
  • Each sub-agent should have unique outputKey

Loop Agent

  • Must have subAgents
  • Should specify maxIterations (default: 3)

Reference Validation

  • Tool references: Each tool ID in tools[] must exist in MCP registry
  • Sub-agent references: Each ID in subAgents[] must be a valid agent ID
  • Model provider: Must be a supported provider with valid credentials

Example Validations

Valid LLM Agent

{
  "id": "research-agent",
  "name": "Research Agent",
  "type": "llm",
  "modelConfig": {
    "provider": "gemini",
    "model": "gemini-2.5-flash"
  },
  "description": "Gathers and summarizes information from various sources",
  "instruction": "You are a research assistant...",
  "tools": ["web_search", "document_reader"],
  "subAgents": [],
  "outputKey": "research_results",
  "isActive": true
}

Invalid Configuration (Missing Fields)

{
  "id": "broken-agent",
  "name": "Broken",
  "type": "llm"
  // MISSING: modelConfig, description, instruction
}

Validation Commands

# Validate Python Pydantic model
uv run python -c "from agent.state.models import AgentConfig; AgentConfig.model_validate(config)"

# Check TypeScript interface
bun run typecheck

Common Issues

  1. Missing description: Orchestrator can't route to agent
  2. Invalid tool references: Tools won't load at runtime
  3. Circular sub-agent references: Causes infinite loops
  4. Missing outputKey in parallel: Results overwrite each other