Tinkuy 0.1.0 — Donde los ríos se encuentran

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

TL;DR:El primer commit que lo inicia todo. Un loop mínimoLLM → tool_calls → execute → feedback

en 467 líneas, provider-agnostic, con budget opcional. Publicado a npm como@carloscortezcloud/tinkuy-agent@0.1.0

.

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.

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ínimodist/

• types

), única dep runtime yaml

, peers opcionales @carloscortezcloud/sayay-guard

y @carloscortezcloud/styrr-llm

"."

, "./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

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

.

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.

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