SDK Reference

The Zil SDK reads your project’s manifest.yaml, identity files, and adapter config, then wires them into a running agent. One function call replaces manual configuration.

`zil.create_agent()`


import zil
 
agent = zil.create_agent()

This returns a fully-configured google.adk.agents.LlmAgent with:

Name and description from manifest.yaml → metadata.name, metadata.description
Model resolved from adapters/llm.yaml → mapped to an ADK-compatible model string
Instruction composed from identity/persona.md + identity/instructions.md + identity/guardrails.yaml
Telemetry configured from observability/config.yaml (if endpoint set)
Guardrail engine loaded from identity/guardrails.yaml → attached as agent._zil_guardrails
Cost tracking initialized from spec.cost → accessible via zil.cost and agent._zil_cost
Environment config populated via zil.config from spec.env declarations

How it works


manifest.yaml
├── metadata.name        →  agent name
├── metadata.description →  agent description
├── spec.runtime.llm.adapter
│   └── adapters/llm.yaml
│       ├── provider     →  model prefix (e.g. "anthropic/")
│       └── model        →  model id (e.g. "claude-sonnet-4-20250514")
└── spec.identity
    └── identity/
        ├── persona.md       →  ┐
        ├── instructions.md  →  ├→  composed instruction string
        └── guardrails.yaml  →  ┘

Parameters

All parameters are optional — by default, everything is read from the project files.

Parameter	Type	Default	Description
`tools`	`list[Callable]`	`[]`	Tool functions to attach to the agent
`project_dir`	`str \| Path`	auto-detect	Project root (walks up from cwd looking for `manifest.yaml`)
`name`	`str`	from manifest	Override agent name
`description`	`str`	from manifest	Override description
`model`	`str`	from adapter	Override model string
`instruction`	`str`	composed	Override the entire instruction
`enable_telemetry`	`bool`	`True`	Auto-setup OTel tracing from `observability/config.yaml`
`enable_guardrails`	`bool`	`True`	Load runtime guardrail engine from `identity/guardrails.yaml`
`enable_cost_tracking`	`bool`	`True`	Track token usage and enforce budgets from `spec.cost`

Adding tools

Tools are plain Python functions. Define them and pass them to create_agent():


import zil
 
 
def lookup_order(order_id: str) -> dict:
    """Look up an order by its ID."""
    return {"order_id": order_id, "status": "shipped"}
 
 
def cancel_order(order_id: str) -> dict:
    """Cancel an order."""
    return {"order_id": order_id, "cancelled": True}
 
 
root_agent = zil.create_agent(
    tools=[lookup_order, cancel_order],
)

ADK automatically generates tool descriptions from the function docstrings and type hints.

Model resolution

The SDK maps adapters/llm.yaml to ADK model strings:

Provider	Model	ADK string
`anthropic`	`claude-sonnet-4-20250514`	`anthropic/claude-sonnet-4-20250514`
`openai`	`gpt-4o`	`openai/gpt-4o`
`vertex-ai`	`gemini-2.0-flash`	`gemini-2.0-flash`

Anthropic and OpenAI use the LiteLLM prefix convention. Vertex/Gemini models are passed directly (ADK native).

Unknown providers fall through as provider/model.

Identity composition

The SDK composes a single instruction string from three files, separated by ---:

persona.md — who the agent is (personality, expertise, tone)
instructions.md — how the agent behaves (rules, format, boundaries)
guardrails.yaml — hard rules, converted to natural-language directives

Guardrails are translated into explicit instructions:

hard_blocks → “You MUST follow these rules… Blocked topics: …”
escalation_triggers → “When condition: message”
output_constraints → “Maximum response length: N characters.”

Overrides

You can override any resolved value:


# Use a different model for testing
agent = zil.create_agent(
    model="openai/gpt-4o-mini",
)
 
# Completely replace the instruction
agent = zil.create_agent(
    instruction="You are a test agent. Always respond with 'OK'.",
)
 
# Point to a different project
agent = zil.create_agent(
    project_dir="/path/to/my-agent",
)

Prerequisites

The SDK requires google-adk. Install it via the [adk] extra:


pip install 'zil-ai[adk]'

Projects scaffolded with zil init include this in requirements.txt automatically.

Generated `agent.py`

When you run zil init my-agent, the generated my_agent/agent.py uses the SDK:


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

The root_agent module-level variable is the ADK convention for agent discovery. The agent lives inside a Python package (my_agent/) so that both zil run and adk run my_agent can discover it.

Note: Zil manifests use kebab-case names (e.g., my-agent), but the module directory uses snake_case (my_agent) to be a valid Python package. The SDK handles this conversion automatically.