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.
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.
| name | agent-config-validator |
|---|---|
| description | 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. |
| allowed-tools | Read, 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
modelConfigwith validproviderandmodel - Must have
instruction(system prompt) outputKeyrecommended 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
- Missing description: Orchestrator can't route to agent
- Invalid tool references: Tools won't load at runtime
- Circular sub-agent references: Causes infinite loops
- Missing outputKey in parallel: Results overwrite each other