title: "Tinkuy 0.1.0 — Donde los ríos se encuentran: un agent framework de 467 líneas"
slug: tinkuy-0-1-0-donde-los-rios-se-encuentran
version: 0.1.0
date: 2026-07-22
tag: v0.1.0
npm: https://www.npmjs.com/package/@carloscortezcloud/tinkuy-agent/v/0.1.0
github: https://github.com/breakingthecloud/tinkuy/releases/tag/v0.1.0
cover: /banners/tinkuy/tinkuy-0-1-0.png
coverDevTo: /banners/tinkuy/tinkuy-0-1-0-devto.png
coverOg: https://tinkuylabs.finoptix.dev/banners/tinkuy/tinkuy-0-1-0.png
commit: e534b48
series: tinkuy-changelog
order: 1

Tinkuy 0.1.0 — Donde los ríos se encuentran

TL;DR: El primer commit que lo inicia todo. Un loop mínimo LLM → tool_calls → execute → feedback en 467 líneas, provider-agnostic, con budget opcional. Publicado a npm como @carloscortezcloud/tinkuy-agent@0.1.0.

Por qué existe Tinkuy

Tinkuy (quechua: encuentro de ríos) es donde tus tools, modelos y budgets convergen en un solo loop. En vez de un framework opinado de 10k líneas, Tinkuy propone ~200 líneas de lógica core y cero lock-in: cualquier Router que cumpla la interfaz funciona, cualquier Guard (Sayay) es opcional.

Qué trae 0.1.0

• src/core/agent.ts — el loop principal: agent.run(prompt) → AgentResult
• src/tools/index.ts — defineTool({ name, description, parameters, execute })
• src/state/index.ts + src/types/index.ts — tipos y estado mínimo
• Empaquetado ESM (dist/ + types), única dep runtime yaml, peers opcionales @carloscortezcloud/sayay-guard y @carloscortezcloud/styrr-llm
• Exports: ".", "./agent", "./tools", "./state"

Metadata: Tag v0.1.0 @ e534b48 · npm 0.1.0 @ 2026-07-22T23:32:13.858Z · Tarball 22 files, 36,209 unpacked

Ejemplo mínimo

import { Agent, defineTool } from '@carloscortezcloud/tinkuy-agent';
import { StyrRouter } from '@carloscortezcloud/styrr-llm';
import { SayayGuard, MemoryStorage } from '@carloscortezcloud/sayay-guard';

const getWeather = defineTool({
  name: 'get_weather',
  description: 'Get current weather for a city',
  parameters: { type: 'object', properties: { city: { type: 'string' } }, required: ['city'] },
  execute: async ({ city }) => ({ temp: 22, condition: 'sunny', city }),
});

const agent = new Agent({
  router: new StyrRouter({ apiKey: process.env.OPENROUTER_API_KEY!, models: [{ id: 'meta-llama/llama-3.3-70b-instruct:free' }] }),
  guard: new SayayGuard({ storage: new MemoryStorage(), budget: { dailyUsd: 5.0 } }),
  tools: [getWeather],
  systemPrompt: 'You are a helpful assistant. Use tools when needed.',
});

const result = await agent.run('What is the weather in Lima?');
// → { text, toolsUsed, iterations, latencyMs, costUsd, toolResults }

Ver examples/01-minimal-agent.mjs.

Por qué importa

Define el contrato minimalista que todo lo demás extiende: Agent({ router, guard, tools, systemPrompt }) + agent.run() + AgentResult. Sin eso no hay ToolRegistry, ni memoria, ni streaming.

Siguiente

0.1.1 — ESM fix → type: module para Node 20+.

---

Verifica: git show v0.1.0 --stat · npm view @carloscortezcloud/tinkuy-agent@0.1.0 --json

Comments

[Kane Lim]

This is a strong foundation for an agent framework, especially because the core abstraction stays intentionally small.

The most interesting part to me is the explicit LLM → tool_calls → execute → feedback loop combined with a provider-agnostic Router. Keeping the execution contract separate from model/provider concerns is a good architectural choice: it makes the framework easier to test, replace components, and evolve without introducing unnecessary coupling.

I also like the decision to make the Guard/budget layer optional. In production, however, I’d be particularly interested in how Tinkuy evolves around failure semantics: malformed tool arguments, tool timeouts, retries, partial tool failures, infinite/near-infinite iteration, idempotency, and cancellation. Those details usually become more important than the initial agent loop once real workloads arrive.

The AgentResult contract is also a good direction. If toolsUsed, iterations, latencyMs, costUsd, and toolResults remain reliable and structured, they can become a useful foundation for observability and evaluation rather than just debugging metadata.

For the next iterations, I’d strongly consider making deterministic testing and evaluation first-class: replayable tool calls, mock routers, bounded execution, structured error states, and metrics around successful vs. failed trajectories. That would give Tinkuy a very practical advantage for teams building agents beyond demos.

467 lines is a compelling constraint. The real test will be whether the framework can preserve that simplicity while adding production-grade reliability without turning into the 10k-line framework it is deliberately avoiding.

I’m interested in where you take the Router/Guard contracts as the ecosystem grows. My team works on AI automation and development systems, and we’re always interested in collaborating with engineers building infrastructure at this layer.