Skip to Content
⚠️ v0.1 — Early preview. APIs and schema may change.
Introduction

Zil Documentation

Zil is a framework for building, validating, packaging, and deploying production AI agents. It composes with ADK , OpenHands , A2A , MCP , DeepEval , OpenTelemetry , and others.

Install

uv pip install zil-ai

This gives you the zil CLI and the Python SDK. Add a framework extra for agent creation:

# Google ADK (default)
uv pip install 'zil-ai[adk]'
 
# OpenHands
uv pip install 'zil-ai[openhands]'
 
# Serve mode (adds FastAPI + uvicorn)
uv pip install 'zil-ai[adk,serve]'

See Frameworks for all supported backends.

What Zil provides

ComponentDescription
Manifest schemaA declarative YAML format (manifest.yaml) describing your agent’s runtime, identity, skills, evals, and observability
zil initScaffolds a working agent project in under 30 seconds
zil validateValidates your project against the spec
zil auditAgent-native security audit — injection resilience, output leakage, identity hardening
zil evalRun, generate, and record evaluation suites
zil packBuilds a versioned .zil archive — a portable agent artifact
zil inspectReads a .zil archive without extracting it
zil pushPush .zil archives to an OCI-compatible registry
zil serveStart the agent as a REST/A2A server with SSE streaming
zil deployDeploy to Google Cloud Run with eval gating
zil.create_agent()Python SDK — reads your manifest and identity files, returns a wired agent

Quick start

# Scaffold a new agent project (creates venv and installs deps)
zil init my-agent
cd my-agent && source .venv/bin/activate
 
# Validate the project
zil validate
 
# Start the agent server
zil serve

The generated my_agent/agent.py wires everything automatically via the SDK:

import zil
 
root_agent = zil.create_agent(
    tools=[],  # add your tool functions here
)

See SDK Reference for the full API.

Project layout

A Zil agent project follows a standard directory structure:

my-agent/
├── manifest.yaml          # Zil agent manifest (the contract)
├── my_agent/              # Agent module
│   ├── __init__.py
│   ├── agent.py           # Agent entry point
│   ├── app.py             # (webhook) FastAPI entry point
│   ├── runner.py          # (webhook) Execution runner
│   └── .env.example       # API key template
├── agents/                # Sub-agent identity directories (multi-agent)
│   ├── vta/identity/
│   └── vtd/identity/
├── skills/                # Reusable agent skills (SKILL.md files)
│   ├── fd-explore-repo/
│   └── fd-submit-changes/
├── tools/                 # MCP server sources (bundled at pack/deploy)
│   └── my-server/
├── adapters/              # LLM and embedding configuration
│   ├── llm.yaml
│   └── embed.yaml
├── identity/              # Root agent persona, instructions, guardrails
│   ├── persona.md
│   ├── instructions.md
│   └── guardrails.yaml
├── evals/                 # Evaluation suite
│   ├── baseline.yaml
│   └── cases/
├── observability/         # OpenTelemetry configuration
│   └── config.yaml
├── Dockerfile             # Container build (auto-generated)
└── .github/workflows/     # CI/CD pipeline

Guiding principles

  1. Built on what exists. Zil composes with ADK, OpenHands, A2A, MCP, DeepEval, OpenTelemetry, and others. We do not reinvent agent orchestration, tool protocols, evaluation, or telemetry.
  2. Declarative-first. The manifest is the contract. The CLI is a thin wrapper that reads, validates, and packages manifests.
  3. No new runtime. Agents run on whatever infrastructure you already have — Cloud Run, Bedrock, Foundry, Kubernetes.
  4. No new registry. Zil uses OCI-compatible registries you already have — Artifact Registry, ECR, GHCR, JFrog.

Community

  • Slack  — join the Zil community for questions, feedback, and discussion
  • GitHub Discussions  — ask questions and share ideas
  • Issues  — report bugs or request features

Next steps

Getting Started