woodwork-engine

Build AI agents with configuration, not code.

Woodwork Engine lets you define AI agents using a simple declarative language (.ww files). Declare what you want—components, connections, and behavior—and Woodwork handles the rest.

Table of Contents

• Why Woodwork?
• Features
• Quick Start
• Documentation
• Examples
• Contributing
• License

Why Woodwork?

Building AI agents usually means:

• Writing boilerplate code over and over
• Managing complex integrations between LLMs, tools, and data sources
• Maintaining brittle orchestration logic

Woodwork takes a different approach: Infrastructure as Code for AI agents.

Instead of writing Python to wire everything together, you declare your agent in a .ww file:

my_agent = agent llm {
    model: language_model
    tools: [web_search, calculator]
}

input = input command_line {
    to: my_agent
}

That's it. Woodwork handles orchestration, tool calling, memory, and communication.

Features

Declarative Configuration

• Define agents in simple .ww files instead of writing Python
• Components are modular and reusable
• Environment variables for secrets ($OPENAI_API_KEY)

Powerful Control Flow

• Hooks: Listen to events for logging and monitoring
• Pipes: Transform data as it flows between components
• Routing: Declarative message passing between components

Rich Integrations

• LLMs: OpenAI, Ollama, HuggingFace
• Knowledge: Vector databases (Chroma), graph databases (Neo4j), text files
• Tools: Function calling, web APIs, command-line tools
• I/O: CLI, voice input/output, streaming

Quick Start

# Install
pip install woodwork-engine

# Create a simple agent configuration
cat > main.ww << 'EOF'
my_llm = llm openai {
  model: "gpt-4o-mini"
  api_key: $OPENAI_API_KEY
}

input = input command_line {
  to: my_llm
}
EOF

# Set up your API key
echo "OPENAI_API_KEY=your-key-here" > .env

# Install dependencies and run
woodwork --init
woodwork

That's it! You now have a running AI agent.

Documentation

• Quickstart Guide - Get up and running in 5 minutes
• Beginner Overview - Understand the core concepts
• Philosophy - Why Infrastructure as Code for agents?
• Control Flow - Master hooks, pipes, and events
• Glossary - Common terms and definitions

Examples

Check out the examples/ directory for ready-to-run configurations:

• 01-short-term-memory-agent/ - Agent with conversational memory
• 02-function-tooling-agent/ - Agent that can call custom functions
• 04-plan-caching-agent/ - Agent with workflow caching for repeated tasks
• message-bus-demo/ - Advanced routing with hooks and pipes

Each example includes a main.ww file and any required Python scripts. Just add your API keys to a .env file and run!

Contributing

We'd love your help! Check out:

• CONTRIBUTING.md - Contribution guidelines
• woodwork-language - VSCode extension for .ww syntax highlighting
• woodwork-website - Documentation website

Roadmap

See the roadmap for planned features and improvements.

License

woodwork-engine uses a GPL license, which can be read in full here.