---

📚 Documentation

- API Reference - Complete TypeDoc-generated API documentation
- v0.2.0 Release Notes - Latest release summary
- Changelog - Version history
- Examples - Working code examples
- Community - Contributing guidelines & discussions
- GitHub Issues - Bug reports & feature requests

---

🎉 What's New in v0.2.0

$3

Budget utilities moved to @thenoo/finops

The budget() function and BudgetManager class are now deprecated in @thenoo/agentkit and will be removed in v1.0.0.

Migration:
``diff
- import { budget, BudgetManager } from '@thenoo/agentkit';
+ import { createBudgetManager, BudgetManager } from '@thenoo/finops';

- const mgr = budget({ usd: 10 });
+ const mgr = createBudgetManager({ usd: 10 });
`

$3

- @thenoo/finops - Dedicated FinOps package with multi-session support and event system
- @thenoo/adapter-openai - OpenAI integration with automatic cost tracking via withFinOps()
- @thenoo/cli - CLI scaffolder (npx @thenoo/cli init) with templates and IDE presets

$3

- FinOps Context - Multi-session cost tracking with createFinOpsContext()
- Adapter Wrapping - withFinOps() for automatic cost tracking and budget enforcement
- Model Degradation - Automatic downgrade to cheaper models on budget breach
- CLI Templates - Minimal, Dashboard, and Serverless project templates
- IDE Integration - Presets for Cursor, GitHub Copilot, and VS Code

$3

- Backward-compatible shim maintains existing API
- Console warnings guide migration path
- All existing v0.1.0 projects continue to work

---

✨ Features

- 🔒 Type-Safe Tools - Zod schemas for input/output validation
- 💰 FinOps Built-In - Real-time budget tracking with configurable guardrails
- 🌍 Edge-Safe - No Node.js APIs; runs in any JavaScript runtime
- 🔌 Provider-Neutral - Works with Azure, OpenAI, local models, or custom LLMs
- 📊 Observable - Structured events ready for OpenTelemetry
- 🧩 Modular - Compose tools, memory, and budget policies

---

📦 Installation

`bash

npm

npm install @thenoo/agentkit zod

pnpm

pnpm add @thenoo/agentkit zod

yarn

yarn add @thenoo/agentkit zod
`

Requirements:
- Node.js ≥18 (or Deno, Cloudflare Workers, etc.)
- TypeScript ≥5.0 (recommended)

---

⚠️ Deprecation Notice

> Budget utilities have moved to @thenoo/finops
>
> The budget() function and BudgetManager class are now deprecated in @thenoo/agentkit and will be removed in v1.0.0.
>
> Migration:
> `diff
> - import { budget, BudgetManager } from '@thenoo/agentkit';
> + import { createBudgetManager, BudgetManager } from '@thenoo/finops';
>
> - const mgr = budget({ usd: 10 });
> + const mgr = createBudgetManager({ usd: 10 });
> `
>
> See the @thenoo/finops documentation for the full API and adapter integration examples.

---

🚀 Quick Start

$3

`typescript
import { z } from 'zod';
import { createAgent, tool } from '@thenoo/agentkit';

// 1. Define a tool with typed input/output
const calculator = tool({
name: 'calculator',
description: 'Perform basic arithmetic',
input: z.object({
operation: z.enum(['add', 'subtract', 'multiply', 'divide']),
a: z.number(),
b: z.number(),
}),
output: z.object({ result: z.number() }),
run: async ({ operation, a, b }) => {
const ops = {
add: a + b,
subtract: a - b,
multiply: a * b,
divide: a / b,
};
return { result: ops[operation] };
},
});

// 2. Create an agent with tools
const agent = createAgent({
name: 'MathAgent',
tools: [calculator],
});

// 3. Run the agent
const result = await agent.run('calculate 15 + 27');
console.log(result.output); // "The result is 42"
`

$3

`typescript
import { createAgent, tool, budget } from '@thenoo/agentkit';

const agent = createAgent({
name: 'BudgetAgent',
tools: [myTool],
budget: budget({
usd: 5.0, // Max $5 per session
perRequestCents: 50, // Max 50¢ per request
onExceed: 'halt', // Stop execution on budget breach
}),
});

// Listen for cost alerts
agent.on('cost:alert', (event) => {
console.error('Budget exceeded!', event.payload);
});

const result = await agent.run('expensive operation');
console.log('Cost:', result.budgetState.totalUsd);
`

---

💰 FinOps: Budget Management

$3

`typescript
import { createAgent, budget } from '@thenoo/agentkit';

const budgetManager = budget({
usd: 10, // $10 session limit
perRequestCents: 100, // $1 per-request limit
onExceed: 'halt', // Policy: halt | truncate | degrade_model
});

const agent = createAgent({
name: 'CostAwareAgent',
budget: budgetManager,
});

// Check budget before expensive operations
if (budgetManager.wouldExceed(estimatedTokens, costPerMToken)) {
console.warn('Operation would exceed budget');
}

// Monitor costs in real-time
agent.on('cost:update', (event) => {
const { totalUsd, requestCount, lastRequestCents } = event.payload;
console.log(Request ${requestCount}: $${lastRequestCents.toFixed(4)} (total: $${totalUsd.toFixed(2)}));
});

// Handle budget alerts
agent.on('cost:alert', (event) => {
const { totalUsd, limitUsd, policy } = event.payload;
if (policy === 'halt') {
throw new Error(Budget exceeded: $${totalUsd} > $${limitUsd});
}
});
`

$3

| Policy | Behavior |
|--------|----------|
| halt | Stop execution immediately and throw an error |
| truncate | Continue with truncated context (reduce token usage) |
| degrade_model | Switch to cheaper model (requires adapter support) |

---

🔧 Tools: Type-Safe Functions

$3

`typescript
import { z } from 'zod';
import { tool } from '@thenoo/agentkit';

const searchTool = tool({
name: 'webSearch',
description: 'Search the web for information',
input: z.object({
query: z.string().min(1),
limit: z.number().int().positive().optional().default(5),
}),
output: z.object({
results: z.array(z.object({
title: z.string(),
url: z.string().url(),
snippet: z.string(),
})),
}),
run: async ({ query, limit }) => {
// Integrate with your search API
const response = await fetch(https://api.search.com?q=${query}&limit=${limit});
return await response.json();
},
});
`

$3

`typescript
import { createRegistry, AnyTool } from '@thenoo/agentkit';

const registry = createRegistry([searchTool, calculatorTool, databaseTool]);

// Get a tool by name
const tool = registry.get('webSearch');

// List all tools
console.log('Available tools:', registry.names());

// Execute a tool with validation
import { executeTool } from '@thenoo/agentkit';
const result = await executeTool(tool, { query: 'AI agents' });
`

---

🧠 Memory: Pluggable Storage

$3

`typescript
import { memory } from '@thenoo/agentkit';

const mem = memory();

await mem.set('user:123', 'Alice', { role: 'admin' });
const record = await mem.get('user:123');
console.log(record?.content); // 'Alice'

const recent = await mem.list(10); // Last 10 records
`

$3

`typescript
import { vectorStore } from '@thenoo/agentkit';

const store = vectorStore();

await store.set('doc1', 'Machine learning basics');
await store.setVector('doc1', [0.1, 0.5, 0.9]); // Embedding

const results = await store.search([0.15, 0.48, 0.92], 5);
results.forEach(({ content, score }) => {
console.log(${content} (similarity: ${score}));
});
`

$3

Implement MemoryProvider or VectorStore for:
- Azure Cosmos DB
- PostgreSQL with pgvector
- Redis
- Pinecone, Weaviate, Qdrant

---

📊 Events & Observability

$3

`typescript
agent.on('agent:start', (event) => {
console.log('Agent started:', event.payload.prompt);
});

agent.on('tool:call', (event) => {
console.log('Tool called:', event.payload.tool);
});

agent.on('tool:result', (event) => {
console.log('Tool result:', event.payload.output);
});

agent.on('cost:update', (event) => {
console.log('Cost update:', event.payload.totalUsd);
});

agent.on('agent:complete', (event) => {
const { output, iterations, budgetState, durationMs } = event.payload;
console.log(Completed in ${durationMs}ms with ${iterations} iterations);
});

agent.on('agent:error', (event) => {
console.error('Agent error:', event.payload.error);
});
`

$3

`typescript
const agent = createAgent({
name: 'TracedAgent',
tracing: true, // Emits trace:span events
});

// Integrate with @opentelemetry/api
// Implementation coming in v0.2.0
`

---

🌍 Edge Runtime Compatibility

@thenoo/agentkit is edge-safe - no Node.js-specific APIs (fs, path, crypto, etc.).

Tested on:
- ✅ Node.js 18+
- ✅ Deno
- ✅ Cloudflare Workers
- ✅ Vercel Edge Functions
- ✅ AWS Lambda@Edge
- ✅ Bun

$3

`typescript
// pages/api/agent.ts
import { createAgent, tool } from '@thenoo/agentkit';

export const config = { runtime: 'edge' };

const agent = createAgent({
name: 'EdgeAgent',
tools: [/ your tools /],
});

export default async function handler(req: Request) {
const { prompt } = await req.json();
const result = await agent.run(prompt);
return new Response(JSON.stringify(result), {
headers: { 'Content-Type': 'application/json' },
});
}
`

---

🏗️ Architecture

`
┌─────────────────────────────────────────┐
│ Agent (Orchestrator) │
│ ┌──────────────────────────────────┐ │
│ │ Tool Registry │ │
│ │ • Validation (Zod) │ │
│ │ • Execution │ │
│ │ • Error handling │ │
│ └──────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────┐ │
│ │ Budget Manager │ │
│ │ • Token tracking │ │
│ │ • Cost calculation │ │
│ │ • Policy enforcement │ │
│ └──────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────┐ │
│ │ Memory Provider │ │
│ │ • Key-value storage │ │
│ │ • Vector search (optional) │ │
│ │ • Pluggable backends │ │
│ └──────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────┐ │
│ │ Event Bus │ │
│ │ • Structured events │ │
│ │ • OpenTelemetry-ready │ │
│ └──────────────────────────────────┘ │
└─────────────────────────────────────────┘
`

Design Principles:
- Core is runtime-agnostic (edge-safe)
- Adapters live in separate packages
- FinOps tracking is opt-in but encouraged
- Memory and tools are pluggable

---

📖 API Reference

Full API documentation is available in the docs/api/ directory, generated with TypeDoc.

$3

Agent Creation
- createAgent(config) - Factory for agent instances
- Agent class - Main execution engine

Tools
- tool({ name, input, output, run }) - Create typed tools
- executeTool(tool, input) - Execute with validation
- ToolRegistry - Manage tool collections
- AnyTool - Type for heterogeneous tool arrays

Budget
- budget(config) - Create budget manager
- BudgetManager - Track costs, enforce limits
- estimateTokens(text) - Rough token count
- calculateTokens(input, output) - Total usage

Memory
- memory() - In-memory provider
- vectorStore() - Stub vector search
- InMemoryProvider - Simple storage
- StubVectorStore - Mock semantic search

Types
- Tool - Generic tool interface
- AgentConfig, AgentResult, ToolCall
- BudgetPolicy, BudgetConfig, BudgetState
- MemoryRecord, MemoryProvider, VectorStore

Utilities
- mask(value, reveal?) - Redact secrets from logs
- schemas - Runtime Zod schemas

---

🧪 Testing

`bash

Run tests

pnpm test

Watch mode

pnpm test:watch

Coverage (requires ≥90%)

pnpm test:coverage
`

Test Coverage:
- 68 tests across 6 suites
- Budget: 21 tests (including guardrails)
- Tools: 16 tests (validation, registry, execution)
- Memory: 11 tests (CRUD, vector search)
- Agent: 11 tests (orchestration, events)
- Types: 9 tests (mask utility, schemas)

---

🚢 Publishing

`bash

Dry-run validation

npm pack --dry-run

Build

pnpm build

Publish to npm

npm publish --access public
`

Package Size:
- Tarball: 15.6 KB
- Unpacked: 53.5 KB
- Minified + Gzipped: ~5.2 KB

---

🛠️ Development

`bash

Clone repo

git clone https://github.com/ZacheryKuykendall/noo.git
cd noo

Install dependencies

pnpm install

Work on agentkit

cd packages/agentkit
pnpm dev # Tests in watch mode
pnpm build # Compile to dist/
pnpm docs # Generate API docs

Run example

cd ../../examples/hello-agent
pnpm start
`

---

🗺️ Roadmap

$3

- [ ] Real LLM adapters (@thenoo/adapter-openai, @thenoo/adapter-azure)
- [ ] Extract @thenoo/finops middleware package
- [ ] Production vector store adapters (Cosmos DB, pgvector)
- [ ] Streaming support for agent responses

$3

- [ ] Multi-agent orchestration
- [ ] OpenTelemetry tracing implementation
- [ ] Advanced budget policies (degrade_model, truncate)
- [ ] Agent-to-agent communication
- [ ] Persistent conversation management

---

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Before submitting:
1. Run pnpm typecheck (zero errors required)
2. Run pnpm test` (all tests must pass)
3. Ensure coverage ≥90% for new code
4. Add JSDoc comments for public APIs

---

📄 License

MIT © The Noo Team

See LICENSE for details.

---

🔗 Links

- GitHub: https://github.com/ZacheryKuykendall/noo
- npm: https://www.npmjs.com/package/@thenoo/agentkit
- Issues: https://github.com/ZacheryKuykendall/noo/issues
- Discussions: https://github.com/ZacheryKuykendall/noo/discussions

---

Built with ❤️ by The Noo Team