Getting Started

Build your first agent in 5 minutes.

1Install

Minimum setup needs Tinkuy + Styrr. Add Sayay and TideRAG as needed.

Core install
npm install @carloscortezcloud/tinkuy-agent @carloscortezcloud/styrr-llm
Optional: with budget + RAG
npm install @carloscortezcloud/tinkuy-agent @carloscortezcloud/styrr-llm @carloscortezcloud/sayay-guard @carloscortezcloud/tiderag

2Get an API Key

Styrr works with any OpenAI-compatible provider. Free options:

OpenRouter— Free models: Nemotron, Gemma, Llama. Recommended →
OpenAI / Bedrock / Any— Just pass your API key and model ID.

3Create a Tool

Tools are type-safe functions the agent can call. Use defineTool.

import { defineTool } from '@carloscortezcloud/tinkuy-agent';

const searchTool = defineTool({
  name: 'search',
  description: 'Search the documentation',
  parameters: {
    type: 'object',
    properties: {
      query: { type: 'string', description: 'Search query' },
      limit: { type: 'number', description: 'query'],
  },
  execute: async (args) => {
    // Your logic — fetch API, query DB, etc.
    return { results: [...] };
  },
});

ℹ The parameters schema follows JSON Schema. The execute function receives validated, typed arguments.

4Create an Agent

import { Agent } 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: 'nvidia/nemotron-3-ultra-550b:free' },
      { id: 'google/gemma-4-31b-it:free' },
    ],
  }),
  guard: new SayayGuard({
    storage: new MemoryStorage(),
    budget: { dailyUsd: 5.0 },
  }),
  tools: [searchTool],
  systemPrompt: 'You are a helpful documentation assistant.',
  maxIterations: 5,
});

5Run Your Agent

const result = await agent.run('Find docs about Cloudflare Workers pricing');

console.log(result.text);         // "Cloudflare Workers have a free tier..."
console.log(result.toolsUsed);    // ['search']
console.log(result.iterations);   // 2
console.log(result.latencyMs);    // 3400
console.log(result.costUsd);      // 0.0001

6Deploy to Cloudflare Workers

Wrap your agent in a Worker and deploy in one command:

// worker.ts
import { Agent } from '@carloscortezcloud/tinkuy-agent';
import { StyrRouter } from '@carloscortezcloud/styrr-llm';

export default {
  async fetch(request, env, ctx) {
    const agent = new Agent({
      router: new StyrRouter({
        apiKey: env.OPENROUTER_API_KEY,
        models: [{ id: 'nvidia/nemotron-3-ultra:free' }],
      }),
      tools: [searchTool],
      systemPrompt: 'You are a helpful assistant.',
    });

    const { query } = await request.json();
    const result = await agent.run(query);
    return Response.json(result);
  },
};
npx wrangler deploy worker.ts

Next Steps

Tinkuy API Reference →

Agent class, defineTool, hooks, options.

Guides →

Deploy guides, examples, best practices.

GitHub Examples →

finops-agent, finops-agent-advanced, streaming.

Live Demo →

SOFE FinOps assistant in production.

← PreviousOverviewNext →Architecture