{"_id":"@aizonaai/adk","_rev":"2-91e9b2e6c207149dab966616ddadd5af","name":"@aizonaai/adk","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@aizonaai/adk","version":"0.1.0","keywords":["ai","agents","adk","aizona","agent-development-kit"],"license":"MIT","_id":"@aizonaai/adk@0.1.0","maintainers":[{"name":"aizonaai","email":"info@aizona.ai"}],"homepage":"https://github.com/ai-zona/AIZona#readme","bugs":{"url":"https://github.com/ai-zona/AIZona/issues"},"bin":{"adk":"dist/bin/adk-cli.js"},"dist":{"shasum":"d03e43771f9f164c5fe6c3f6d51025aa9b668c67","tarball":"https://registry.npmjs.org/@aizonaai/adk/-/adk-0.1.0.tgz","fileCount":16,"integrity":"sha512-NGTX85Dsx+lNuuLk514ZPfq9iB/MH/a+BbkIN7XvR6jDAOeyDj0hFexPLx7kyhL0O+lWln9ucp69IGRHlKnA8Q==","signatures":[{"sig":"MEUCIGJrkkjO2NB9EfEcamKIvkSl4v+TU5A8QS2nLHajN0hgAiEA/9OXi/mivG61XY1qDRBiZwAGAxIju0RrRuwReiGwGzg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aizonaai%2fadk@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":1910503},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"7da10b14f01db26b4545defda865ba3b1831f857","scripts":{"test":"vitest run","build":"tsup","build:tsc":"tsc","typecheck":"tsc --noEmit","test:watch":"vitest","prepublishOnly":"pnpm build"},"_npmUser":{"name":"aizonaai","email":"info@aizona.ai"},"repository":{"url":"git+https://github.com/ai-zona/adk.git","type":"git","directory":"packages/adk"},"_npmVersion":"10.8.2","description":"AIZona Agent Development Kit — Build, deploy, and orchestrate AI agents","directories":{},"_nodeVersion":"20.20.2","dependencies":{"zod":"^3.24.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","vitest":"^4.0.18","typescript":"^5.7.3","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/adk_0.1.0_1779768128106_0.29018527499260793","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@aizonaai/adk","version":"0.1.1","description":"AIZona Agent Development Kit — Build, deploy, and orchestrate AI agents","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"bin":{"adk":"dist/bin/adk-cli.js"},"scripts":{"build":"tsup","build:tsc":"tsc","typecheck":"tsc --noEmit","test":"vitest run","test:watch":"vitest","prepublishOnly":"pnpm build"},"dependencies":{"zod":"^3.24.1"},"devDependencies":{"@types/node":"^20.0.0","tsup":"^8.5.1","typescript":"^5.7.3","vitest":"^4.0.18"},"keywords":["ai","agents","adk","aizona","agent-development-kit"],"license":"MIT","engines":{"node":">=18"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/ai-zona/adk.git","directory":"packages/adk"},"homepage":"https://github.com/ai-zona/AIZona#readme","bugs":{"url":"https://github.com/ai-zona/AIZona/issues"},"_id":"@aizonaai/adk@0.1.1","gitHead":"93993be263726837a07900cc265344fa6bdee690","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-1dQ4escl6mitGmrAUv7Dlff+Xw+mrDIiwsPsjJPriiShO9pJLVOZKVR84rJCqfSH98u1OoeE2kpsCnDwWYmfMw==","shasum":"13d853e4fd2f27562e61f0caa70b5befe9fe8f30","tarball":"https://registry.npmjs.org/@aizonaai/adk/-/adk-0.1.1.tgz","fileCount":16,"unpackedSize":2081036,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aizonaai%2fadk@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBrFiM8+V0RWt7rtJDoem0+I/cnu57z++8WA4pZ1gncRAiB+qfngNrBu1Ch0xBYMG+e9yuR+uHKTx1M2oQhMvsZ+uA=="}]},"_npmUser":{"name":"aizonaai","email":"info@aizona.ai"},"directories":{},"maintainers":[{"name":"aizonaai","email":"info@aizona.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/adk_0.1.1_1779819063536_0.24626312719974308"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-26T04:02:07.925Z","modified":"2026-05-26T18:11:04.043Z","0.1.0":"2026-05-26T04:02:08.355Z","0.1.1":"2026-05-26T18:11:03.737Z"},"bugs":{"url":"https://github.com/ai-zona/AIZona/issues"},"license":"MIT","homepage":"https://github.com/ai-zona/AIZona#readme","keywords":["ai","agents","adk","aizona","agent-development-kit"],"repository":{"type":"git","url":"git+https://github.com/ai-zona/adk.git","directory":"packages/adk"},"description":"AIZona Agent Development Kit — Build, deploy, and orchestrate AI agents","maintainers":[{"name":"aizonaai","email":"info@aizona.ai"}],"readme":"# @aizonaai/adk\n\n[![npm version](https://img.shields.io/npm/v/@aizonaai/adk.svg)](https://www.npmjs.com/package/@aizonaai/adk)\n[![npm downloads](https://img.shields.io/npm/dm/@aizonaai/adk.svg)](https://www.npmjs.com/package/@aizonaai/adk)\n[![license](https://img.shields.io/npm/l/@aizonaai/adk.svg)](LICENSE)\n[![node](https://img.shields.io/node/v/@aizonaai/adk.svg)](https://nodejs.org)\n\n**Agent Development Kit** — build, deploy, and orchestrate AI agents in TypeScript. Zero runtime dependencies beyond `zod`. Dual ESM + CJS publish, full TypeScript declarations, npm provenance.\n\n```bash\nnpm install @aizonaai/adk\n# or\npnpm add @aizonaai/adk\n# or\nyarn add @aizonaai/adk\n```\n\n> Requires Node ≥ 20.\n\n---\n\n## Five-minute quick start\n\n```typescript\nimport { AnthropicProvider, Runner, defineAgent } from \"@aizonaai/adk\";\n\nconst agent = defineAgent({\n  name: \"tutor\",\n  model: \"claude-haiku-4-5-20251001\",\n  instructions: \"You are a patient programming tutor. Keep answers under 6 sentences.\",\n});\n\nconst runner = new Runner({\n  provider: new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY! }),\n});\n\nconst { output, usage } = await runner.run(agent, { input: \"What is a closure?\" });\nconsole.log(output);\nconsole.log(`cost: $${usage.totalCostUsd.toFixed(6)}`);\n```\n\nThat's the entire surface for a single-agent program. From here you add tools, guardrails, handoffs, and streaming as you need them.\n\n---\n\n## What you can build\n\n| Capability | API entry point | Example |\n| ---------- | --------------- | ------- |\n| Single agent with custom instructions | `defineAgent`, `Runner` | [01-basic-agent](https://github.com/ai-zona/adk/tree/main/examples/01-basic-agent) |\n| Tools with Zod-validated inputs | `defineTool` | [web-scraper](https://github.com/ai-zona/adk/tree/main/examples/web-scraper) |\n| Multi-agent handoffs (Swarm pattern) | `defineAgent({ handoffs })` | [02-multi-agent](https://github.com/ai-zona/adk/tree/main/examples/02-multi-agent) |\n| Guardrails (content, PII, budget, consent) | `contentFilter`, `piiFilter`, `budgetLimit`, `consentGate` | [03-guardrails](https://github.com/ai-zona/adk/tree/main/examples/03-guardrails) |\n| Token-by-token streaming | `runner.stream()`, `streamToSSE` | [04-streaming](https://github.com/ai-zona/adk/tree/main/examples/04-streaming) |\n| MCP server integration | `mcpServerTools` | [05-mcp-tools](https://github.com/ai-zona/adk/tree/main/examples/05-mcp-tools) |\n| Vector memory with decay | `MemoryManager`, `PgVectorMemoryBackend` | — |\n| Multi-provider routing | `ADKRouter` | — |\n| Sandboxed code execution | `CodeExecutor`, `createExecuteCodeTool` | — |\n| Evaluation harness | `defineEvalSuite`, `runEval` | — |\n| Voice / realtime | `RealtimeAgent` | — |\n\n---\n\n## BYOK (bring your own key)\n\nThe ADK is **provider-agnostic and standalone**. You hold the API keys; the SDK never phones home.\n\n```typescript\nimport { createProvider } from \"@aizonaai/adk\";\n\n// Local development — your key, your bill\nconst provider = createProvider({\n  providerId: \"anthropic\",         // or \"openai\" | \"google\" | \"xai\" | \"ollama\" | \"lmstudio\"\n  apiKey: process.env.ANTHROPIC_API_KEY,\n});\n```\n\nFor production deployments, put `@aizonaai/adk-server` in front so clients never see the provider key — they present a short-lived ADK key that you mint and validate. See [docs/security.md](https://github.com/ai-zona/adk/blob/main/docs/security.md) for the full pattern.\n\n### Supported providers\n\n| Provider | `providerId` | Notes |\n| -------- | ------------ | ----- |\n| Anthropic | `anthropic` | Claude family |\n| OpenAI | `openai` | GPT family + structured outputs |\n| Google | `google` | Gemini family |\n| xAI | `xai` | Grok family |\n| Ollama | `ollama` | Self-hosted; set `OLLAMA_BASE_URL` |\n| LM Studio | `lmstudio` | Self-hosted; OpenAI-compatible |\n\n---\n\n## Core APIs\n\n### `defineAgent(config)`\n\n```typescript\nconst agent = defineAgent({\n  name: \"my-agent\",\n  model: \"claude-sonnet-4-5-20250929\",\n  instructions: \"You are a helpful assistant.\", // string or (ctx) => string\n  description: \"Short description for handoff discovery\",\n  tools: [myTool],\n  guardrails: [contentFilter()],\n  handoffs: [{ agent: otherAgent, description: \"Specialized tasks\" }],\n  outputSchema: z.object({ answer: z.string() }),\n  consentLevel: \"auto\", // auto | notify | explicit | multi_party\n  maxTurns: 25,\n});\n```\n\n### `defineTool(config)`\n\n```typescript\nimport { z } from \"zod\";\n\nconst search = defineTool({\n  name: \"search\",\n  description: \"Search the web\",\n  inputSchema: z.object({ query: z.string() }),\n  execute: async ({ query }, ctx) => ({ results: await api(query) }),\n  hooks: {\n    preExecute: async (input) => input,    // modify or block\n    postExecute: async (output) => output, // transform result\n  },\n});\n```\n\n### `Runner`\n\n```typescript\nconst runner = new Runner({ provider, eventBus, defaultMaxTurns: 25 });\n\n// One-shot\nconst result = await runner.run(agent, {\n  input: \"Hello\",\n  messages: [],         // prior conversation\n  sessionId: \"s-123\",\n  maxTurns: 10,\n  signal: abort.signal,\n});\n\n// Streaming\nfor await (const event of runner.stream(agent, { input: \"Hello\" })) {\n  if (event.type === \"text_delta\") process.stdout.write(event.content);\n  if (event.type === \"run_complete\") console.log(event.result.usage);\n}\n```\n\n### Guardrails\n\n```typescript\nimport { contentFilter, piiFilter, budgetLimit, consentGate } from \"@aizonaai/adk\";\n\ndefineAgent({\n  // …\n  guardrails: [\n    contentFilter({ blockedTerms: [\"ignore previous\"] }),\n    piiFilter({ redact: true }),\n    budgetLimit({ maxCostUsd: 0.50 }),\n    consentGate({ level: \"explicit\" }),\n  ],\n});\n```\n\nTripwire violations throw `GuardrailTripwireError` — catch at the call site.\n\n### Multi-agent\n\n```typescript\nimport { ParallelRunner, Team, agentAsTool } from \"@aizonaai/adk\";\n\n// Handoff routing\nconst router = defineAgent({\n  name: \"router\",\n  handoffs: [\n    { agent: codeAgent, description: \"Code questions\" },\n    { agent: mathAgent, description: \"Math questions\" },\n  ],\n});\n\n// Parallel fan-out\nconst parallel = new ParallelRunner();\nconst results = await parallel.run([agent1, agent2], { input: \"Analyze this\" });\n\n// Wrap an agent as a tool\nconst researchTool = agentAsTool(researchAgent, \"Research a topic deeply\");\n```\n\n### Provider routing\n\n```typescript\nimport { ADKRouter } from \"@aizonaai/adk\";\n\nconst router = new ADKRouter({\n  providers: [anthropic, openai],\n  strategy: \"balanced\", // cost-optimized | latency-optimized | quality-optimized | balanced | fallback-chain\n});\n```\n\n### Skills\n\n```typescript\nimport { defineSkill } from \"@aizonaai/adk\";\n\nconst summarize = defineSkill({\n  name: \"summarize\",\n  description: \"Summarize a document\",\n  execute: async (input, ctx) => {\n    const r = await ctx.runner.run(summarizerAgent, { input: input.text });\n    return { summary: r.output };\n  },\n});\n```\n\n### Memory\n\n```typescript\nimport { MemoryManager, EmbeddingService, PgVectorMemoryBackend } from \"@aizonaai/adk\";\n\nconst memory = new MemoryManager({\n  backend: new PgVectorMemoryBackend(dbClient),\n  embeddings: new EmbeddingService({ provider: anthropic }),\n});\n\nawait memory.storeMemory({ content: \"User prefers TypeScript\", type: \"fact\" });\nconst hits = await memory.searchMemories(\"programming language preference\");\n```\n\n### Event bus\n\n```typescript\nimport { ADKEventBus } from \"@aizonaai/adk\";\n\nconst bus = new ADKEventBus();\nbus.on(\"run.started\",     (e) => console.log(\"→\", e.runId));\nbus.on(\"tool.invoked\",    (e) => console.log(\"  tool:\", e.toolName));\nbus.on(\"run.completed\",   (e) => console.log(\"✓\", e.usage.totalCostUsd, \"USD\"));\n```\n\n### MCP integration\n\n```typescript\nimport { mcpServerTools } from \"@aizonaai/adk\";\n\nconst tools = await mcpServerTools({ transport: \"http\", url: \"http://localhost:3000/mcp\" });\nconst agent = defineAgent({ name: \"mcp-agent\", tools });\n```\n\n### Eval harness\n\n```typescript\nimport { defineEvalSuite, runEval } from \"@aizonaai/adk\";\n\nconst suite = defineEvalSuite({\n  name: \"factuality\",\n  cases: [{ input: \"Capital of France?\", expected: /Paris/i }],\n});\n\nconst report = await runEval(suite, agent, { runner });\nconsole.log(report.passRate);\n```\n\n---\n\n## Architecture\n\n- **Turn loop** — messages → LLM call → tool execution → guardrails → handoff check → repeat.\n- **Standalone** — zero platform coupling. Works against any supported provider.\n- **Type-safe** — full TypeScript with Zod validation on every boundary.\n- **Composable** — tools, guardrails, handoffs, and skills mix freely.\n- **Observable** — structured event bus, distributed tracing, streaming-first transport.\n\n---\n\n## Documentation\n\n| Guide | What it covers |\n| ----- | -------------- |\n| [docs/deployment.md](https://github.com/ai-zona/adk/blob/main/docs/deployment.md) | Docker, Compose, Railway, Vercel, Kubernetes, sizing |\n| [docs/security.md](https://github.com/ai-zona/adk/blob/main/docs/security.md) | Keys, CORS, rate limiting, validation, secrets, guardrails |\n| [docs/troubleshooting.md](https://github.com/ai-zona/adk/blob/main/docs/troubleshooting.md) | Common errors, debug mode, perf, memory leaks |\n| [examples/](https://github.com/ai-zona/adk/tree/main/examples) | Six runnable examples covering the production surface |\n\nIssues and feature requests: [github.com/ai-zona/adk/issues](https://github.com/ai-zona/adk/issues).\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","readmeFilename":"README.md"}