LangSpace is a declarative language for composing AI agent workflows. It provides a readable, versionable format for defining agents, tools, and multi-step pipelines that can be executed directly or compiled to other targets.

LangSpace sits between writing raw Python/TypeScript and using no-code builders. It captures the full specification of an AI workflow in a single file that can be version-controlled, shared, and executed.

agent "code-reviewer" {
  model: "claude-sonnet-4-20250514"
  temperature: 0.3

  instruction: ```
    You are a senior code reviewer. Analyze code for security
    vulnerabilities, performance issues, and best practices.
  ```

  tools: [read_file, search_codebase]
}

intent "review-changes" {
  use: agent("code-reviewer")
  input: git.diff(base: "main")
  output: file("review.md")
}

go get github.com/shellkjell/langspace

LangSpace uses block-based declarations with key-value properties.

Files represent static data: prompts, configuration, or output destinations.

# Inline contents
file "prompt.md" {
  contents: ```
    You are a helpful assistant.
  ```
}

# Reference to external file
file "config.json" {
  path: "./config/app.json"
}

Agents are LLM-powered actors with specific roles and capabilities.

agent "analyst" {
  model: "claude-sonnet-4-20250514"
  temperature: 0.5

  instruction: ```
    Analyze the provided data and generate insights.
  ```

  tools: [read_file, query_database]
}

Tools extend agent capabilities by connecting to external systems.

tool "search_codebase" {
  description: "Search for patterns in source code"

  parameters: {
    query: string required
    file_pattern: string optional
  }

  handler: mcp("filesystem-server")
}

Intentions express what you want to accomplish.

intent "summarize-docs" {
  use: agent("summarizer")
  input: file("docs/**/*.md")
  output: file("summary.md")
}

Pipelines chain multiple agents together with data flowing between steps.

pipeline "analyze-and-report" {
  step "analyze" {
    use: agent("analyzer")
    input: $input
  }

  step "report" {
    use: agent("reporter")
    input: step("analyze").output
  }

  output: step("report").output
}

Connect to Model Context Protocol servers for tool access.

mcp "filesystem" {
  command: "npx"
  args: ["-y", "@anthropic/mcp-filesystem", "/workspace"]
}

agent "file-manager" {
  tools: [
    mcp("filesystem").read_file,
    mcp("filesystem").write_file,
  ]
}

Scripts enable code-first agent actions — a more efficient alternative to multiple tool calls. Instead of loading full data into the context window through repeated tool invocations, agents write executable code that performs complex operations in a single execution.

# Define a reusable script template
script "db-update" {
  language: "python"
  runtime: "python3"

  capabilities: [database]

  parameters: {
    table: string required
    id: string required
    updates: object required
  }

  code: ```python
    import db

    # Find, modify, and save in one execution
    record = db.find(table, {"id": id})
    record.update(updates)
    db.save(table, record)

    print(f"Updated {table}/{id}")
  ```

  timeout: "30s"
}

# Agent that generates and executes scripts
agent "efficient-data-manager" {
  model: "claude-sonnet-4-20250514"

  instruction: ```
    Perform database operations by writing Python scripts
    rather than making individual tool calls. This is more
    efficient and keeps the context window small.
  ```

  scripts: [script("db-update")]
}

Why Scripts over Tools?

See examples/09-scripts.ls for more patterns.

Set global defaults for providers and models.

config {
  default_model: "claude-sonnet-4-20250514"

  providers: {
    anthropic: {
      api_key: env("ANTHROPIC_API_KEY")
    }
  }
}

Single-line comments start with #:

# This is a comment
agent "example" { }  # Inline comment

import (
    "github.com/shellkjell/langspace/pkg/parser"
    "github.com/shellkjell/langspace/pkg/workspace"
)

// Parse LangSpace definitions
input := `
agent "reviewer" {
  model: "claude-sonnet-4-20250514"
  instruction: "Review code for issues"
}
`

p := parser.New(input)
entities, err := p.Parse()
if err != nil {
    log.Fatal(err)
}

// Add to workspace
ws := workspace.New()
for _, entity := range entities {
    ws.AddEntity(entity)
}

# Execute a workflow
langspace run workflow.ls --input ./src

# Compile to Python
langspace compile --target python workflow.ls -o workflow.py

See the examples/ directory:

Current Parser Capabilities:

• Nested blocks (e.g., step { } inside pipeline { }) ✅
• Typed parameters (e.g., query: string required "description") ✅
• Inline typed blocks (e.g., handler: http { ... }) ✅
• Property access chains (e.g., params.location) ✅
• Inline enums (e.g., type: enum ["a", "b", "c"]) ✅

Not Yet Implemented:

• Method calls on objects (git.staged_files())
• Comparison expressions (env("X") == "true")
• Control flow (branch, loop, break_if)

Examples marked as "Partial" demonstrate syntax that's partially supported.

langspace/
├── cmd/langspace/     # CLI application
├── pkg/
│   ├── ast/           # Entity types and interfaces
│   ├── parser/        # Language parser
│   ├── slices/        # Generic slice utilities
│   ├── tokenizer/     # Lexical analysis
│   ├── validator/     # Entity validation
│   └── workspace/     # Workspace management

Current Phase: Foundation

• Block-based tokenizer with DSL syntax support
• Parser for entity declarations with nested blocks and typed parameters
• AST representation with entity metadata and relationships
• Nested entity parsing (pipelines with steps, tools with handlers)
• Typed parameter declarations (name: string required "desc")
• Property access chains (params.location, config.defaults.timeout)
• Validation framework with extensible custom validators
• Workspace management with entity hooks, events, snapshots, and persistence
• Error recovery parsing with detailed line/column error reporting
• Comprehensive test coverage (100+ tests)

• Nested block parsing (step inside pipeline, parallel blocks)
• Typed parameters (query: string required)
• LLM integration and execution runtime
• Script execution sandbox
• Compilation targets (Python/LangGraph, TypeScript)
• Full CLI tool (langspace run, langspace compile)

See ROADMAP.md for the full development plan and PRD.md for the product specification.

Contributions are welcome. See CONTRIBUTING.md for guidelines.

• Go 1.23+
• Make (optional, for build automation)

go test ./...
go test -bench=. -benchmem ./...
go test -race ./...

GNU GPL v2