Validation Playground

The Valgent playground provides an interactive environment for testing and validating AI agent cards. This powerful tool helps you experiment with different configurations and get instant feedback.

Overview

The playground offers multiple ways to validate agent cards:

JSON Editor - Direct editing with syntax highlighting
Form Builder - Visual form interface for beginners
File Upload - Drag and drop validation
URL Import - Load agent cards from remote URLs

Getting Started

JSON Editor Mode

The JSON editor provides a full-featured development environment:

{
  "agent_id": "example-agent",
  "version": "1.0.0",
  "name": "Example AI Agent",
  "description": "A sample agent for testing validation",
  "capabilities": [
    {
      "type": "text_processing",
      "description": "Process and analyze text content"
    }
  ],
  "endpoints": [
    {
      "url": "https://api.example.com/agent",
      "method": "POST",
      "parameters": {
        "input": "string",
        "options": "object"
      }
    }
  ]
}

Editor Features

Syntax Highlighting - JSON syntax coloring
Auto-completion - Field suggestions based on A2A schema
Error Indicators - Real-time syntax error highlighting
Line Numbers - Easy navigation and error reporting
Bracket Matching - Visual bracket pair highlighting

Form Builder Mode

For users who prefer a visual interface:

Basic Information
- Agent ID (required)
- Version (semantic versioning)
- Name and description
- Tags and categories
Capabilities
- Add/remove capability entries
- Define capability types and descriptions
- Set input/output schemas
Endpoints
- Configure API endpoints
- Set HTTP methods and parameters
- Define authentication requirements
Metadata
- Author information
- License details
- Documentation links

Validation Features

Real-time Validation

As you type or make changes, the playground provides:

Live Error Checking - Immediate feedback on validation issues
Schema Compliance - Ensures adherence to A2A protocol
Quality Scoring - Real-time quality metrics and suggestions

Detailed Error Reports

When validation fails, you'll see:

{
  "valid": false,
  "errors": [
    {
      "path": "$.endpoints[0].url",
      "message": "Invalid URL format",
      "severity": "error",
      "line": 12,
      "column": 15,
      "suggestion": "Use a valid HTTP/HTTPS URL"
    }
  ],
  "warnings": [
    {
      "path": "$.description",
      "message": "Description is shorter than recommended minimum",
      "severity": "warning",
      "suggestion": "Consider adding more detail to help users understand your agent"
    }
  ]
}

Quality Analysis

Beyond basic validation, get insights on:

Completeness Score - How thoroughly documented your agent is
Best Practices - Recommendations for improvement
Security Analysis - Potential security considerations
Performance Hints - Optimization suggestions

Advanced Features

Schema Validation Levels

Choose your validation strictness:

Basic Validation

Required field presence
Data type validation
Format compliance

Standard Validation (Default)

All basic validation rules
Recommended field validation
Best practice warnings

Strict Validation

All standard validation rules
Optional field validation
Style guide compliance

Custom Schema Extensions

For advanced users, validate against custom schema extensions:

{
  "$schema": "https://schemas.valgent.io/agent-card/v0.2.6",
  "extensions": {
    "x-custom-field": "Custom validation rules",
    "x-organization": {
      "team": "AI Development",
      "project": "Production Agents"
    }
  }
}

Batch Validation

Validate multiple agent cards simultaneously:

Click Batch Mode in the toolbar
Upload multiple JSON files or paste multiple JSON objects
Review validation results for each card
Export combined validation report

Import and Export

Supported Import Formats

File Upload

JSON Files - Direct agent card files
YAML Files - Alternative format support
ZIP Archives - Multiple files at once

URL Import

# Import from public URL
https://github.com/user/repo/blob/main/agent-card.json

# Import from API endpoint
https://api.example.com/agents/my-agent/card

Clipboard Import

Paste JSON directly from clipboard
Auto-detect and format JSON content
Support for minified JSON

Export Options

Validation Results

JSON Report - Detailed validation results
PDF Summary - Human-readable report
CSV Data - Spreadsheet-compatible format

Agent Cards

Formatted JSON - Prettified output
Minified JSON - Compact format
YAML Format - Alternative representation

Generate shareable links for your validation sessions:

https://valgent.io/playground?session=abc123def456

Features:

Read-only Links - Share without edit permissions
Temporary Sessions - Auto-expire after 24 hours
Version History - Track changes in shared sessions

Embed Playground

Embed the playground in your documentation:

<iframe 
  src="https://valgent.io/playground/embed?template=basic"
  width="100%" 
  height="600px"
  frameborder="0">
</iframe>

Templates and Examples

Quick Start Templates

Pre-built templates for common use cases:

Basic Text Agent

{
  "agent_id": "text-processor",
  "version": "1.0.0",
  "name": "Text Processing Agent",
  "capabilities": [
    {
      "type": "text_processing",
      "input_schema": {
        "type": "object",
        "properties": {
          "text": {"type": "string"}
        }
      }
    }
  ]
}

{
  "agent_id": "multimodal-agent",
  "version": "1.0.0",
  "name": "Multi-modal Processing Agent",
  "capabilities": [
    {
      "type": "text_processing",
      "description": "Process text content"
    },
    {
      "type": "image_analysis",
      "description": "Analyze image content"
    }
  ]
}

Community Examples

Browse agent cards shared by the community:

Popular Templates - Most-used configurations
Industry Examples - Sector-specific agents
Best Practices - Exemplary implementations

Keyboard Shortcuts

| Shortcut | Action | |----------|--------| | Ctrl/Cmd + Enter | Validate current content | | Ctrl/Cmd + S | Save current session | | Ctrl/Cmd + K | Open command palette | | Ctrl/Cmd + / | Toggle comments | | Ctrl/Cmd + D | Duplicate line | | Ctrl/Cmd + F | Find and replace | | Alt + Up/Down | Move line up/down | | Ctrl/Cmd + Z | Undo | | Ctrl/Cmd + Y | Redo |

Integration Options

API Integration

Use the playground's validation engine in your applications:

const response = await fetch('https://api.valgent.io/v1/validate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    agent_card: yourAgentCard
  })
});

CI/CD Integration

Integrate validation into your deployment pipeline:

# GitHub Actions example
- name: Validate Agent Card
  uses: valgent/validate-action@v1
  with:
    agent-card-path: './agent-card.json'
    api-key: ${{ secrets.VALGENT_API_KEY }}