Skip to content

Agent Script Specification & Tools

A comprehensive toolkit for defining, validating, and converting AI agent specifications between JSON and Markdown formats.

Agent Script Tools provides structured specifications for AI agents, including their capabilities, interaction models, MCP integrations, and behavioral rules. Build production-ready AI agent configurations with type-safe validation and seamless format conversion.

Quick Start

Get up and running with Agent Script Tools in minutes:

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# Clone the repository
git clone https://github.com/theagenticguy/agent-script.git
cd agent-script

# Install dependencies
uv sync --all-groups

# Try the example commands
uv run agent-script-json
uv run agent-script-markdown

Key Features

  • Structured Specifications

    Define AI agents with comprehensive Pydantic models including capabilities, tools, and interaction workflows

    Learn more

  • Bi-directional Conversion

    Seamlessly convert between JSON and Markdown formats with full fidelity preservation

    See examples

  • MCP Integration

    Native support for Model Context Protocol server integration and tool management

    MCP guide

Command Line Interface

The toolkit provides rich CLI commands for working with agent specifications:

Bash
1
2
3
4
5
6
7
8
# Show example agent in JSON format
uv run agent-script-json

# Show example agent in Markdown format  
uv run agent-script-markdown

# Show the JSON schema
uv run show-spec-json
Bash
1
2
3
4
5
# Convert JSON to Markdown
uv run convert-to-markdown examples/ai-engineer.json

# Convert Markdown to JSON
uv run convert-to-json examples/ai-engineer.md
Bash
1
2
# Generate JSON schemas from models
uv run generate-schema

Project Architecture

This workspace contains two complementary packages:

  • agent-script-tools

    CLI toolkit with conversion drivers and command implementations

    • Rich command-line interface
    • JSON ↔ Markdown conversion logic
    • Example specifications and templates

  • agent-script-spec

    Pydantic models defining the agent specification structure

    • Type-safe data models
    • Validation and serialization
    • JSON schema generation

Example Usage

Here's a simple example of working with agent specifications:

Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
from agent_script_spec.models import AgentScriptSpecification
from agent_script_tools.drivers import to_markdown, from_markdown

# Load specification from JSON
with open("examples/ai-engineer.json") as f:
    spec = AgentScriptSpecification.model_validate_json(f.read())

# Convert to Markdown
markdown = to_markdown(spec)
print(f"Agent: {spec.name}")
print(f"Tools: {len(spec.frontmatter.tools)}")

# Convert back from Markdown
spec_from_md = from_markdown(markdown)
assert spec == spec_from_md  # Round-trip conversion preserves data

What's Next?

  • Installation Guide

    Detailed setup instructions and development environment configuration

    Get started

  • Specification Format

    Complete reference for the agent specification format and all available fields

    Learn format

  • API Reference

    Full API documentation for all classes, functions, and modules

    Browse API

  • Examples

    Real-world examples and use cases for different types of AI agents

    View examples

Built with Python 3.13+, Pydantic, and uv