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 , A2A , MCP , DeepEval , and OpenTelemetry .

Install

pip install zil-ai

This gives you the zil CLI and the Python SDK. For agent creation with ADK:

pip install 'zil-ai[adk]'

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 runRuns your agent interactively (wraps adk run)
zil webStarts the ADK web UI for testing
zil deployDeploy to Google Cloud Run with eval gating
zil.create_agent()Python SDK — reads your manifest and identity files, returns a wired ADK 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
 
# Run the agent interactively
zil run
 
# Or start the ADK web UI
zil web

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/              # ADK agent module
│   ├── __init__.py
│   ├── agent.py           # Agent entry point
│   └── .env.example       # API key template
├── adapters/              # LLM and embedding configuration
│   ├── llm.yaml
│   └── embed.yaml
├── identity/              # Agent persona, instructions, guardrails
│   ├── persona.md
│   ├── instructions.md
│   └── guardrails.yaml
├── evals/                 # Evaluation suite
│   ├── baseline.yaml
│   └── cases/
├── observability/         # OpenTelemetry configuration
│   └── config.yaml
├── Dockerfile             # Container build
└── .github/workflows/     # CI/CD pipeline

Guiding principles

  1. Built on what exists. Zil composes with ADK, A2A, MCP, DeepEval, and OpenTelemetry. 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