🤖 Kastor: Bringing Infrastructure-as-Code to AI Agents

"Kastor is essentially Terraform for AI agents."

Currently, the industry defines agents through imperative code within frameworks like CrewAI or LangGraph, or via manual clicking in proprietary UIs like AWS Bedrock or OpenAI Assistants. This leaves developers without a vendor-neutral, version-controlled, or peer-reviewable source of truth.

Kastor solves this by introducing a typed, declarative specification system using HCL (HashiCorp Configuration Language) via .agent, .tool, and .prompt files.

🛠️ The Toolchain Architecture

Kastor utilizes a Go-based toolchain that offers two primary operational paths:

1. kastor build: Transforms declarative specs into runnable projects for specific target frameworks.
2. kastor plan / kastor apply: Manages agents as persistent resources on hosted platforms, featuring state management, diffing, and drift detection.

Workflow Visualization

🚀 Current State & Roadmap

The project is evolving rapidly. Here is the current status of the feature set:

Immediate Goals:

• Implement kastor plan/apply logic.
• Enable local state tracking.
• Build native AWS/Azure platform providers.

📝 Example Specification

An agent in Kastor is defined by a concise HCL block. For instance, a weather agent might look like this:

agent "weather" {
  description = "Answers weather questions for a location and date"
  model = model.web_search 

  input "location" {
    type        = string
    description = "The location to get weather for"
  }

  input "date" {
    type     = string
    optional = true
  }

  output "weather" {
    type = string
  }
}

📥 Installation

Depending on your environment, you can install Kastor using one of the following methods:

⚡ Quickstart: Building the Weather Agent

Prerequisites

• Go $\ge 1.26$
• Python $\ge 3.11$
• API Keys: OpenAI and Tavily (for the MCP search tool).

Step 1: Compile the Spec

First, validate and build the project from the example directory:

go build ./cmd/kastor
./kastor validate examples/weather/
./kastor build examples/weather/

Note: The output is written to examples/weather/gen/langgraph. This directory is not committed to Git because it is deterministically reproducible from the spec.

Step 2: Environment Setup

cd examples/weather/gen/langgraph
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Step 3: MCP Configuration

The web_search tool uses a Model Context Protocol (MCP) URI: mcp://search-server/tavily_search. To connect to the server, create a mcp_servers.json file (which is .gitignore'd for security):

{
  "search-server": {
    "transport": "streamable_http",
    "url": "https://mcp.tavily.com/mcp/?tavilyApiKey=tvly-YOUR-KEY"
  }
}

Warning: Ensure the tool name (tavily_search) matches the server's advertised tools exactly.

Step 4: Execution

Export your credentials and run the agent:

export OPENAI_API_KEY=sk-...
python3 main.py weather --inputs '{"location": "Lisbon", "date": "tomorrow"}'

Expected Output:

{ "weather": "... [Weather Data] ..." }

⚠️ Important Considerations

Dependency Handling

As per $\text{SPEC.md } \xi 3.2/\xi 4$, if agent.weather references an output from agent.forecast via an optional input:

• The reference is validated at compile time.
• The dependency graph is ordered accordingly.
• However, the generated code will not automatically trigger the upstream agent. You must run the upstream agent manually and pass the result via --inputs.

Documentation

• SPEC.md: The definitive source for all design decisions.
• CLAUDE.md: Guidelines for daily development conventions.

💬 Feedback & Community

The author is seeking input from developers building production-grade agents.

• GitHub: Star the repo or open an issue for bugs/design suggestions.
• Discord: Join the early community via the invite link.
• Website: www.getkastor.dev

License: Apache-2.0