Introduction

agntz is an open-source agent framework where agents are declared as YAML — not code — and run unchanged in three places: embedded in your app (@agntz/sdk for TypeScript, agntz for Python), on the hosted cloud (agntz.co), or on infrastructure you control (self-host). Every run is traced. Every save is a version. Bring your own model keys.

These docs are optimized for both humans and LLMs. Every page is also available as raw markdown — see the Copy button at the top of each page, or fetch /llms.txt for the full corpus.

What you can build

• Single-call agents — an LLM with an instruction, optional tools, optional structured output.
• Pipelines — sequential and parallel agents that compose other agents into multi-step workflows with loops and conditionals.
• Tool agents — deterministic function calls with no LLM in the loop.
• Long-running conversations — sessions persist message history across calls.
• Streaming UIs — full event stream (tokens, tool calls, replies) over Server-Sent Events.
• Multi-tenant products — every record is user-scoped on the hosted edition.

Three things stay the same as you scale from your laptop to production:

1. The YAML schema. One manifest.yaml runs in embedded mode, hosted mode, and self-hosted mode.
2. The client API. client.agents.run(...) — the same resource shape in TypeScript and Python, with language-native argument names.
3. The observability model. Runs, spans, and traces work identically in every edition.

Choose your starting point

Install

# Embedded: run agents in-process from YAML files
pnpm add @agntz/sdk

# Hosted client: call agents on agntz.co or your own worker
pnpm add @agntz/client

# Optional persistence for embedded mode
pnpm add @agntz/store-sqlite

# CLI (run via npx or install globally)
npm i -g @agntz/sdk

Node 20+ for TypeScript. Python 3.11+ for Python. @agntz/client is universal across browser, Node, and edge runtimes; embedded SDKs read YAML from disk and run in your process.

Set the provider API key your agents will use:

export OPENAI_API_KEY=sk-...
# or ANTHROPIC_API_KEY=sk-ant-...
# or GOOGLE_GENERATIVE_AI_API_KEY=...
# or OPENROUTER_API_KEY=sk-or-...   # 300+ models incl. open-source via one key

agntz calls providers directly with your key — no proxy, no data routing. OpenRouter is available as a meta-provider when you want access to many models (Anthropic, Google, Meta, DeepSeek, open-source) with a single API key — use provider: openrouter and a slug like anthropic/claude-sonnet-4 or meta-llama/llama-3.3-70b-instruct.

Where to go next

• New here? Start with the Quickstart.
• Prefer the terminal? Jump to CLI getting started.
• Want the big picture? Read Defining agents and The four agent kinds.
• Looking for a specific field? The Schema section is the complete reference.