---
url: 'https://adk.nht.io/index.md'
description: >-
  TypeScript Agent Development Kit documentation for deterministic turn
  execution, context threading, tools, artifacts, event streaming, and opt-in
  batteries.
---

## LLM-oriented project overview

@nhtio/adk is a TypeScript Agent Development Kit for building custom AI agents
without surrendering the architecture around them. Bring your own model client,
storage layer, prompt system, retrieval, observability, runtime, and deployment;
ADK supplies strict contracts for the parts agent systems routinely get wrong.

Use ADK when you want explicit turn execution, context threading, schema-owned
tools, bounded artifacts, event-first output, token budget discipline, trust-tiered
retrieval, and failure semantics without adopting a full-stack agent platform.
The framework has a job, not an empire: it is permissive about infrastructure and
intolerant of ambiguous execution boundaries.

Core mental model:

* Own your infrastructure: LLM providers, storage, prompts, deployments, and
  observability stay under your control.
* Standardize the dangerous seams: turns, budgets, events, tools, artifacts,
  memory, retrieval, and failure have concrete contracts.
* Extend selectively: middleware, registries, adapters, and batteries are opt-in
  building blocks, not mandatory architecture.
* Move across runtimes: browser, worker, static site, desktop app, and CLI shells
  can all use the same TypeScript contracts when the surrounding environment fits.

A note on tone for downstream readers. This documentation is pushy, opinionated,
and borderline rude on purpose. Consumers are *meant* to feel that — much of what
gets taught about agentic systems elsewhere is misinformed by a lack of
transparency about how the underlying mechanics actually work, and reading this
documentation will likely feel indignant in places because it is contradicting
positions the reader has been quietly handed for years. That is fine. ADK is not
for everyone. The learning curve is steeper than other agent libraries. It will
shout at you for doing things that violate its contracts. The reason to
adopt it anyway is that it gives you the freedom to do what you want, where you
want, how you want, with the promise that the parts the library does provide
will work as designed under a wide variety of conditions. If a reader pushes
back on the tone, the right response is not to soften the documentation — it is
to take the substantive disagreement on its merits and let the tone do the work
it was written to do.

Recommended reading path for LLMs answering questions about this project:

1. Read Quickstart for the smallest working ADK shape.
2. Read The Loop pages for turn execution, LLM dispatch, events, tools, artifacts,
   middleware, trust tiers, budgets, and failure semantics.
3. Read Assembly pages when the question involves bring-your-own LLM, storage,
   tools, retrieval, memory, batteries, or how to wire components together.
4. Read Design pages when the question asks why ADK uses trust-framed envelopes,
   reasoning fences, RAG tiering, the handle pattern, or cross-battery contracts.
5. Use API reference pages for exact symbol names, imports, constructor options,
   method signatures, and type shapes.