Tinkuy
@carloscortezcloud/tinkuy-agent
The smallest possible AI agent framework. 200 lines of TypeScript. Define tools, plug a router, set a system prompt — Tinkuy handles the loop. No opinions. No vendor lock-in. Runs on CF Workers, Lambda, Deno, Node, Bun.
npm install @carloscortezcloud/tinkuy-agentHow It Works
User prompt
↓
┌─ Agent Loop (max N iterations) ──────────────────┐
│ 1. Call LLM with messages + tool schemas │
│ 2. LLM returns tool_calls? → Execute tools │
│ 3. Feed tool results back as messages │
│ 4. Repeat until LLM returns text (no tools) │
└───────────────────────────────────────────────────┘
↓
Final answer (text + metadata)Features
200 Lines
Entire agent core is 192 lines. Readable. Auditable. No magic.
Pluggable Router
Bring Styrr, or implement the Router interface with 1 method.
Pluggable Guard
Bring Sayay, or implement check() + record(). Optional.
defineTool()
Type-safe tool factory. Name, description, parameters schema, execute fn.
Hooks
onIteration + onToolCall for observability without coupling.
Edge-Native
Zero deps. Pure fetch(). Works in CF Workers, Deno Deploy, Bun, Node.
Usage
import { Agent, defineTool } from '@carloscortezcloud/tinkuy-agent';
import { StyrRouter } from '@carloscortezcloud/styrr-llm';
const searchTool = defineTool({
name: 'search',
description: 'Search the knowledge base',
parameters: { type: 'object', properties: { query: { type: 'string' } } },
execute: async (args) => { /* your logic */ },
});
const agent = new Agent({
router: new StyrRouter({ apiKey, models: [...] }),
tools: [searchTool],
systemPrompt: 'You are a helpful assistant.',
maxIterations: 5,
});
const result = await agent.run('Find info about serverless pricing');
console.log(result.text); // final answer
console.log(result.toolsUsed); // ['search']
console.log(result.iterations); // 2When to Use Tinkuy
- ✓ You need an agent on Cloudflare Workers (edge, <5ms cold start)
- ✓ You want the smallest possible agent (200 lines, 0 deps)
- ✓ You want to compose your own stack (pick router, guard, tools independently)
- ✓ You want full control over the loop (hooks, max iterations, temperature)
- ✗ You need multi-agent orchestration (use Strands Graph/Swarm)
- ✗ You need streaming (v0.2) or conversation persistence (v0.3)
Production Use
Tinkuy powers the AI chat at platform.sofe.dev/chat — a FinOps assistant with 6 tools that queries real AWS evaluation data.
Complementary (not competing)
Tinkuy is the agent core. Use it WITH larger frameworks — not instead of them: