Guides

Step-by-step guides for building and deploying agents with the Almost-Zero Stack.

🚀

Deploy an Agent to Cloudflare Workers

Wrap your Tinkuy agent in a Worker and deploy globally in under 5 minutes. Edge cold starts in <5ms. Your bill stays near $0.

1. Project setup

npm create cloudflare@latest my-agent -- --template worker
cd my-agent
npm install @carloscortezcloud/tinkuy-agent @carloscortezcloud/styrr-llm

2. Write the worker

import { Agent, defineTool } 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: [],
      systemPrompt: 'You are a helpful assistant.',
    });

    const { query } = await request.json();
    const result = await agent.run(query);
    return Response.json(result);
  },
};

3. Set secrets & deploy

npx wrangler secret put OPENROUTER_API_KEY
npx wrangler deploy

That's it. Your agent is live on every Cloudflare edge location. $0/mo infrastructure.

💰

Build a FinOps Agent

Learn from the production SOFE agent. Full code at github.com/breakingthecloud/tinkuylabs.

Basic →Advanced (RAG + Budget) →Streaming →

📐

Best Practices

1. Always set a budget — Even in development. Sayay with dailyUsd: 1.0 prevents runaway loops.

2. Use free models for dev — OpenRouter free tier (Nemotron, Gemma) costs $0. Switch to paid for production.

3. Set maxIterations — Default is 10. Most agents should complete in 2-3 iterations. Lower = safer.

4. Use onComplete hook — Log every agent run. Track cost, iterations, and tools used per user.

5. Keep tools focused — One tool = one responsibility. The LLM decides the chain.

🔄

Migrating from LangChain / Strands

Tinkuy is complementary — you can use Styrr and Sayay WITH your existing framework:

Styrr as ChatModel — Use StyrrRouter wherever you'd use ChatOpenAI in LangChain. Drop-in replacement with automatic fallback.

Sayay as Plugin — Add SayayGuard as a middleware/plugin in Strands to enforce per-user budgets.

Tinkuy for edge — Replace full LangChain with Tinkuy when deploying to Workers. 200 lines vs 50MB+ of deps.

← PreviousRecipe — Multi-Model Fallback