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 and supports modular imports for large projects.

Import other LangSpace files to share definitions.

import "common/agents.ls"
import "prompts/reviewer.md"

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)
}

# Parse a file and show statistics
langspace parse -file workflow.ls

# Execute a workflow
langspace run -file workflow.ls -name my-intent

# Start a server for triggers (HTTP/SSE)
langspace serve -file triggers.ls -port 8080

# Compile to Python/LangGraph
langspace compile --target python -file workflow.ls -output ./out

# Validate syntax and rules
langspace validate -file workflow.ls

# Start Language Server (LSP) for IDE support
langspace lsp

A VS Code extension for LangSpace is available in the vscode-langspace/ directory. It provides:

• Syntax highlighting for .ls files
• Intelligent IDE support (Go to Definition) via LSP
• Language configuration and snippets

To install manually:

code --install-extension vscode-langspace/langspace-0.1.0.vsix

Current Phase: Integration & Compilation

• Block-based Syntax: Full DSL support with nested blocks and typed parameters
• Expression Parser: Method calls (str.upper()), comparisons (x == y), and control flow (branch, loop)
• Direct Execution: Built-in runtime with Anthropic/OpenAI/Ollama support
• Tool Orchestration: Auto-management of tool loops and MCP server integration
• Scripting: Sandboxed Python/Shell execution for context-efficient actions
• Compilation: Python/LangGraph target generation via langspace compile
• Automation: Trigger engine for scheduled and event-driven workflows
• Workspace: Full persistence, snapshoting, and versioning system
• CLI: Comprehensive toolset (parse, run, validate, serve, compile)
• Modular Imports: Multi-file support with import statements and recursive loading
• Intelligent IDE Support: Full "Go to Definition" support across files via LSP server
• Test Coverage: 160+ tests covering core logic, imports, and LSP features

• TypeScript Compilation: Target generation for Node.js/Deno
• Cloud Hosting: Managed deployment for LangSpace workflows
• Advanced Debugging: Step-by-step execution visualization
• Security: Granular RBAC and secret management

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

• Go 1.23+
• Docker Desktop (for local CI)
• act (for local CI)

To run GitHub Actions locally and ensure quality before pushing, run:

make setup-local-ci

This will configure a git pre-push hook that runs the CI suite (test and build jobs) locally using act.

make test

You can also run the local CI manually:

make local-ci

Contributions are welcome. See CONTRIBUTING.md for guidelines.

GNU GPL v2