@aizonaai/adk 0.1.0

package/examples/email-assistant/README.md

@@ -0,0 +1,39 @@
+# Email Assistant
+
+An agent that drafts emails using a structured tool with Zod validation.
+
+## Run
+
+```bash
+ANTHROPIC_API_KEY=<your-key> npx tsx index.ts \
+  "Draft a follow-up to sarah@example.com about last week's Q3 review"
+```
+
+## What it does
+
+- Defines a `draft_email` tool with a rich Zod schema (email, enum, defaults)
+- The agent parses the user's natural language request and calls the tool
+- In a real app, the tool would call SendGrid / Gmail API / Nodemailer
+
+## Key APIs
+
+```ts
+defineTool({
+  name: "draft_email",
+  inputSchema: z.object({
+    to: z.string().email(),
+    subject: z.string(),
+    body: z.string(),
+    tone: z.enum(["professional", "friendly", "formal"]).default("professional"),
+  }),
+  execute: async ({ to, subject, body, tone }) => { /* send or save */ },
+})
+```
+
+## Extend it
+
+- Add a `send_email` tool that actually delivers via your email provider
+- Wire up Gmail API with OAuth using the ADK `ProxyRouter`
+- Add a guardrail to require explicit confirmation before sending
+
+See the [ADK README](../../README.md) for the full API reference.

package/examples/email-assistant/index.ts

@@ -0,0 +1,71 @@
+/**
+ * Email Assistant — agent with a structured draft tool
+ *
+ * Demonstrates:
+ *  - defineTool() with rich Zod schema (enum, default, email validation)
+ *  - Side-effectful tool (in a real app, this would call your email API)
+ *  - Agent instructions that guide multi-step behaviour
+ *
+ * Run:
+ *   ANTHROPIC_API_KEY=<key> npx tsx index.ts \
+ *     "Draft a follow-up to sarah@example.com about last week's Q3 review"
+ */
+
+import { z } from "zod";
+import { AnthropicProvider, Runner, defineAgent, defineTool } from "@aizonaai/adk";
+
+const draftEmailTool = defineTool({
+  name: "draft_email",
+  description: "Create an email draft with the specified recipient, subject, and body",
+  inputSchema: z.object({
+    to: z.string().email().describe("Recipient email address"),
+    subject: z.string().describe("Email subject line (concise, under 60 chars)"),
+    body: z.string().describe("Full email body text"),
+    tone: z
+      .enum(["professional", "friendly", "formal"])
+      .default("professional")
+      .describe("Writing tone"),
+  }),
+  execute: async ({ to, subject, body, tone }) => {
+    // In a real app: call SendGrid, Nodemailer, Gmail API, etc.
+    console.log("\n─── EMAIL DRAFT ───────────────────────────────");
+    console.log(`To:      ${to}`);
+    console.log(`Subject: ${subject}`);
+    console.log(`Tone:    ${tone}`);
+    console.log();
+    console.log(body);
+    console.log("───────────────────────────────────────────────\n");
+    return {
+      success: true,
+      draftId: `draft_${Date.now()}`,
+      message: `Draft saved for ${to}`,
+    };
+  },
+});
+
+const agent = defineAgent({
+  name: "email-assistant",
+  instructions: `You are an expert email writing assistant.
+
+When asked to write or draft an email:
+1. Identify the recipient, subject, and purpose from the user's request
+2. Choose an appropriate tone (professional by default)
+3. Call draft_email to create the draft
+4. Confirm what you drafted and offer to adjust tone or content
+
+Write clear, concise emails. Avoid filler phrases like "I hope this email finds you well."`,
+  model: "claude-haiku-4-5-20251001",
+  tools: [draftEmailTool],
+});
+
+const runner = new Runner({
+  provider: new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY! }),
+});
+
+const result = await runner.run(agent, {
+  input:
+    process.argv[2] ??
+    "Draft a professional follow-up email to sarah@acmecorp.com about the Q3 budget review meeting we had last week.",
+});
+
+console.log(result.output);

package/examples/hello-world/README.md

@@ -0,0 +1,25 @@
+# Hello World
+
+The simplest possible ADK agent — one file, no tools, no config.
+
+## Run
+
+```bash
+ANTHROPIC_API_KEY=<your-key> npx tsx index.ts "Hello!"
+```
+
+## What it does
+
+- Creates an agent with a name, instructions, and a model
+- Runs it with the `Runner` and prints the response
+- Shows token usage and cost per run
+
+## Key APIs
+
+```ts
+defineAgent({ name, instructions, model })
+new Runner({ provider })
+runner.run(agent, { input: "..." }) → RunResult
+```
+
+See the [ADK README](../../README.md) for the full API reference.

package/examples/hello-world/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Hello World — minimal ADK agent
+ *
+ * The simplest possible agent: a name, instructions, and a model.
+ * No tools, no sessions, no multi-agent routing — just a direct chat.
+ *
+ * Run:
+ *   ANTHROPIC_API_KEY=<key> npx tsx index.ts "Hello!"
+ */
+
+import { AnthropicProvider, Runner, defineAgent } from "@aizonaai/adk";
+
+const agent = defineAgent({
+  name: "hello-world",
+  instructions:
+    "You are a friendly assistant. Greet users warmly and answer their questions concisely.",
+  model: "claude-haiku-4-5-20251001",
+});
+
+const runner = new Runner({
+  provider: new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY! }),
+});
+
+const result = await runner.run(agent, {
+  input: process.argv[2] ?? "Hello! What can you do?",
+});
+
+console.log(result.output);
+console.log(
+  `\n[${result.usage.totalCostUsd.toFixed(6)} USD | ${result.usage.inputTokens + result.usage.outputTokens} tokens]`,
+);

package/examples/web-scraper/README.md

@@ -0,0 +1,36 @@
+# Web Scraper
+
+An agent that fetches and summarizes web content using a custom tool.
+
+## Run
+
+```bash
+ANTHROPIC_API_KEY=<your-key> npx tsx index.ts "Summarize https://example.com"
+```
+
+## What it does
+
+- Defines a `fetch_url` tool with Zod input schema validation
+- The agent decides when to call the tool based on the user's request
+- Strips HTML and truncates to fit within the context window
+
+## Key APIs
+
+```ts
+defineTool({
+  name: "fetch_url",
+  description: "...",
+  inputSchema: z.object({ url: z.string().url() }),
+  execute: async ({ url }) => { /* ... */ return string },
+})
+
+defineAgent({ name, instructions, tools: [fetchUrlTool] })
+```
+
+## Extend it
+
+- Add authentication headers for paywalled sites
+- Parse structured data (JSON-LD, Open Graph) instead of stripping HTML
+- Chain with another agent to generate a report from multiple URLs
+
+See the [ADK README](../../README.md) for the full API reference.

package/examples/web-scraper/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Web Scraper — agent with a custom fetch tool
+ *
+ * Demonstrates:
+ *  - defineTool() with Zod input schema
+ *  - Tool execution with error handling
+ *  - Agent with tool access
+ *
+ * Run:
+ *   ANTHROPIC_API_KEY=<key> npx tsx index.ts "Summarize https://example.com"
+ */
+
+import { z } from "zod";
+import { AnthropicProvider, Runner, defineAgent, defineTool } from "@aizonaai/adk";
+
+const fetchUrlTool = defineTool({
+  name: "fetch_url",
+  description: "Fetch the text content of a URL and return it as plain text",
+  inputSchema: z.object({
+    url: z.string().url().describe("The full URL to fetch"),
+  }),
+  execute: async ({ url }) => {
+    const res = await fetch(url, {
+      headers: { "User-Agent": "Mozilla/5.0 (compatible; ADK-Example/1.0)" },
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText}`);
+    const html = await res.text();
+    // Strip tags and collapse whitespace — good enough for demo purposes
+    const text = html.replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
+    return text.slice(0, 8_000);
+  },
+});
+
+const agent = defineAgent({
+  name: "web-scraper",
+  instructions: `You are a web research assistant.
+Use the fetch_url tool to retrieve content from URLs the user provides.
+After fetching, extract and summarize the key information they asked for.
+If a fetch fails, report the error and suggest alternatives.`,
+  model: "claude-haiku-4-5-20251001",
+  tools: [fetchUrlTool],
+});
+
+const runner = new Runner({
+  provider: new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY! }),
+});
+
+const result = await runner.run(agent, {
+  input:
+    process.argv[2] ?? "Fetch https://example.com and summarize what the page is about.",
+});
+
+console.log(result.output);

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@aizonaai/adk",
+  "version": "0.1.0",
+  "description": "AIZona Agent Development Kit \u2014 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"
+  },
+  "files": [
+    "dist",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "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": "https://github.com/ai-zona/adk",
+    "directory": "packages/adk"
+  },
+  "homepage": "https://github.com/ai-zona/AIZona#readme",
+  "bugs": {
+    "url": "https://github.com/ai-zona/AIZona/issues"
+  }
+}