AgenticScript is a programming language designed specifically for distributed agent systems. It provides first-class support for agent spawning, inter-agent communication, tool management, and coordination patterns that are essential for modern AI applications.

• Agent-First Design: Native syntax for spawning and managing AI agents
• Inter-Agent Communication: Built-in message passing with ask and tell operations
• Tool Management: Dynamic tool assignment and execution framework
• Message Bus: Thread-safe communication with delivery guarantees
• Rich Debugging: Live agent status, call graphs, and performance metrics
• Module System: Import and organize agent types and tools
• High Performance: Threading-based concurrent execution

• Python 3.12 or higher
• UV package manager (recommended) or pip

# Clone the repository
git clone https://github.com/yourusername/agenticscript.git
cd agenticscript

# Install dependencies with UV
uv sync --dev

# Or with pip
pip install -e .

Create a file called hello_agents.as:

import agenticscript.stdlib.tools { WebSearch, AgentRouting }

// Spawn multiple agents with different capabilities
agent coordinator = spawn Agent{ openai/gpt-4o }
agent researcher = spawn Agent{ claude/sonnet }
agent analyzer = spawn Agent{ gemini/pro }

// Configure agent goals and tools
*coordinator->goal = "Coordinate research and analysis tasks"
*researcher->goal = "Research information using web search"
*analyzer->goal = "Analyze research data"

*coordinator->tools = { AgentRouting{ researcher, analyzer } }
*researcher->tools = { WebSearch }

// Inter-agent synchronous communication
coordination_response = coordinator.ask("What is your current status?")
print("Coordinator status:")
print(coordination_response)

// Inter-agent asynchronous communication
researcher.tell("Start research on AI trends")
analyzer.tell("Prepare for data analysis")

Run your program:

uv run agenticscript hello_agents.as

AgenticScript includes a rich terminal-based REPL with debugging capabilities:

> agenticscript

AgenticScript REPL v0.1.0
Type 'help debug' for debug commands

🤖> <your agenticscript code>

Available debug commands:

• debug agents - Show all active agents and their status
• debug tools - Display tool registry and usage statistics
• debug messages - View message bus performance metrics
• debug flow - Visualize agent communication patterns
• debug stats - Comprehensive system statistics
• debug dump <agent> - Detailed agent information

🤖> debug agents
                               Active Agents
┏━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┓
┃ ID        ┃ Name        ┃ Model         ┃ Status ┃ Goal                 ┃
┡━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━┩
│ agent_001 │ coordinator │ openai/gpt-4o │ idle   │ Coordinate resear... │
│ agent_002 │ researcher  │ claude/sonnet │ idle   │ Research informat... │
│ agent_003 │ analyzer    │ gemini/pro    │ idle   │ Analyze research ... │
└───────────┴─────────────┴───────────────┴────────┴──────────────────────┘

• Agent Lifecycle Management: Spawn, configure, and coordinate agents
• Communication Primitives: Direct agent-to-agent messaging
• Tool Integration: Pluggable tool system with registry management
• Control Flow: Conditional logic and boolean expressions
• Import System: Modular organization of agent types and tools
• Variable Assignment: Full expression evaluation and storage

• Message Bus: Priority queue-based message delivery
• Tool Registry: Plugin-pattern architecture for extensible tools
• Threading Model: Background processing and concurrent operations
• Debug Interface: Rich terminal-based debugging with live statistics
• Performance Monitoring: Message flow visualization and usage patterns

• WebSearch: Simulated web search capabilities
• AgentRouting: Dynamic message routing between agents
• Calculator: Mathematical operations and computations
• FileManager: File system operations and management

// Spawn an agent with a specific model
agent myAgent = spawn Agent{ openai/gpt-4o }

// Set agent properties
*myAgent->goal = "Process user requests"
*myAgent->temperature = 0.7
*myAgent->max_tokens = 1000

// Import tools from stdlib
import agenticscript.stdlib.tools { WebSearch, Calculator }

// Assign tools to agents
*myAgent->tools = { WebSearch, Calculator }

// Check tool availability and execute
if myAgent.has_tool("WebSearch") {
    result = myAgent.execute_tool("WebSearch", "latest AI research")
    print(result)
}

// Synchronous communication (ask/response)
response = agent1.ask("What is your status?")

// Asynchronous communication (fire and forget)
agent2.tell("Process this data")

// Agent routing for coordination
*coordinator->tools = { AgentRouting{ worker1, worker2, worker3 } }

// Conditional execution
if agent.status == "idle" {
    agent.tell("Start processing")
} else {
    print("Agent is busy")
}

// Boolean expressions
if agent.has_tool("WebSearch") and agent.status == "ready" {
    search_result = agent.execute_tool("WebSearch", "query")
}

import agenticscript.stdlib.tools { WebSearch, AgentRouting }

// Create specialized agents
agent research_coordinator = spawn Agent{ openai/gpt-4o }
agent web_researcher = spawn Agent{ claude/sonnet }
agent data_analyst = spawn Agent{ gemini/pro }
agent report_writer = spawn Agent{ openai/gpt-4o }

// Configure the pipeline
*research_coordinator->goal = "Coordinate research pipeline"
*research_coordinator->tools = { AgentRouting{ web_researcher, data_analyst, report_writer } }

*web_researcher->tools = { WebSearch }
*data_analyst->goal = "Analyze research data"
*report_writer->goal = "Generate research reports"

// Execute the pipeline
if research_coordinator.has_tool("AgentRouting") {
    research_coordinator.tell("Start research on quantum computing")

    // Check pipeline status
    status = research_coordinator.ask("What is the pipeline status?")
    print(status)
}

import agenticscript.stdlib.tools { Calculator, FileManager }

agent math_agent = spawn Agent{ openai/gpt-4o }
*math_agent->tools = { Calculator, FileManager }

if math_agent.has_tool("Calculator") {
    result = math_agent.execute_tool("Calculator", "2 + 2 * 3")
    print("Calculation result:")
    print(result)
}

AgenticScript is built on a robust architecture designed for scalability and extensibility:

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Lark Parser   │ -> │  AST Transformer │ -> │ Tree Interpreter│
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                                         │
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│  Message Bus    │ <- │   Tool Registry  │ <- │  Agent System   │
└─────────────────┘    └──────────────────┘    └─────────────────┘

• Parser: Lark-based grammar with EBNF syntax definitions
• AST: Comprehensive node hierarchy for all language constructs
• Interpreter: Tree-walking interpreter with runtime value system
• Message Bus: Thread-safe inter-agent communication
• Tool Registry: Plugin architecture for extensible functionality
• Debug System: Rich introspection and performance monitoring

agenticscript/
├── src/agenticscript/
│   ├── core/                 # Core language implementation
│   │   ├── grammar.lark      # Language grammar definition
│   │   ├── ast_nodes.py      # AST node definitions
│   │   ├── parser.py         # Parser and transformer
│   │   ├── interpreter.py    # Tree-walking interpreter
│   │   └── module_system.py  # Import resolution
│   ├── runtime/              # Runtime systems
│   │   ├── message_bus.py    # Inter-agent communication
│   │   └── tool_registry.py  # Tool management
│   ├── stdlib/               # Standard library
│   │   ├── tools.py          # Built-in tools
│   │   └── agents.py         # Standard agent types
│   └── debugger/             # Debug interface
│       └── repl.py           # Interactive REPL
├── tests/                    # Comprehensive test suite
├── docs/                     # Documentation
└── examples/                 # Example programs

# Run all tests
uv run python -m pytest tests/

# Run specific test categories
uv run python tests/test_parser.py
uv run python tests/test_interpreter.py
uv run python tests/test_phase2_integration.py

# Run enhanced debug tests
uv run python tests/test_enhanced_debug.py

We welcome contributions! Please see our Contributing Guide for details. # TODO

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with tests
4. Run the test suite (uv run python -m pytest)
5. Commit your changes (git commit -m 'feat: add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

• Language Reference # TODO
• API Documentation # TODO
• Architecture Guide # TODO
• Examples Gallery # TODO
• Development Notes

This project is licensed under the MIT License - see the LICENSE file for details.

• Built with Lark for parsing
• Terminal interface powered by Rich
• Package management with UV
• Inspired by distributed systems and agent-oriented programming research