Example agents built with the Tinkuy ecosystem
FinOps, streaming, budget control — runnable examples you can use today.

Examples · Quick Start · The Stack · Build Your Own

---

What's Inside

Example	Description	Features
finops-agent	AWS cost analysis with simulated data	Agent.run(), tools, guardrails, onComplete hook
finops-agent-advanced	Auto-discovery models, RAG, real API, budget guards	Agent.run(), fallback chain, onComplete hook
finops-agent-streaming	Agent.stream() with AG-UI events	text_delta, tool_call_result, done
deterministic-ontology-aws	TokenOps AWS reference: Step Functions + Lambda blueprints	ASL, ontology validator, CDK stack, 3 Lambda blueprints
sayay-styrr-agentcore	Strands agent with Sayay budget + Styrr cross-provider on AgentCore	checkOrThrow() kill switch, DynamoStorage, fallback chain

Quick Start

# Clone and run any example
git clone https://github.com/breakingthecloud/tinkuylabs.git
cd tinkuylabs/finops-agent
pnpm install
export OPENROUTER_API_KEY=sk-or-...  # Free models available
pnpm start

From the repo root (pnpm workspace):

pnpm install
pnpm --filter finops-agent start
pnpm --filter finops-agent-advanced start
pnpm --filter finops-agent-streaming start

The Stack

Each example uses the Tinkuy ecosystem — three composable packages:

┌─────────────────────────────────────────────────┐
│                  Your Agent                       │
├─────────────────────────────────────────────────┤
│  @carloscortezcloud/tinkuy-agent  (agent loop)   │
│  @carloscortezcloud/styrr-llm     (LLM routing)  │
│  @carloscortezcloud/sayay-guard   (cost guard)   │
└─────────────────────────────────────────────────┘

Package	Role
Tinkuy	Tool loop engine — call LLM → parse tools → execute → repeat
Styrr	Multi-model router with automatic fallback
Sayay	Budget guardrails — set daily/monthly limits, block/warn/degrade

Get a Free API Key

1. Go to openrouter.ai
2. Sign up → Keys → Create Key
3. Free models (no credit card): nvidia/nemotron-3-super-120b:free, meta-llama/llama-3.3-70b-instruct:free

Build Your Own

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

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: 1.0 },
  }),
  tools: [/* your tools */],
  systemPrompt: 'You are a helpful assistant.',
});

const result = await agent.run('Say hello');
console.log(result.text);

Observability Hooks

Each example uses onComplete to print run stats:

const agent = new Agent({
  onComplete: (event) => {
    console.log(`Iterations: ${event.iterations}`);
    console.log(`Tools: ${event.toolsUsed.join(', ')}`);
    console.log(`Models: ${event.modelsUsed.join(', ')}`);
    console.log(`Latency: ${event.totalLatencyMs}ms`);
  },
});

In production, this hook pushes data to Qhaway for cost/latency observability.

Streaming

The finops-agent-streaming example uses Agent.stream():

for await (const event of agent.stream(prompt)) {
  if (event.type === 'text_delta') process.stdout.write(event.text);
  if (event.type === 'tool_call_result') console.log(`Tool: ${event.tool}`);
  if (event.type === 'done') console.log(`Done in ${event.totalLatencyMs}ms`);
}

Ecosystem

Package	Role
Tinkuy	Agent framework
Styrr	LLM router
Sayay	Cost guardrails
Qhaway	Agent observability
TideRAG	Edge RAG pipeline

License

Apache 2.0.

---

Tinkuy · Styrr · Sayay · Qhaway · TideRAG