Installation

npm install @carloscortezcloud/tinkuy-agent @carloscortezcloud/styrr-llm

Minimal Agent

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

const searchTool = defineTool({
  name: 'search',
  description: 'Search the knowledge base',
  parameters: {
    type: 'object',
    properties: { query: { type: 'string' } },
    required: ['query'],
  },
  execute: async (args) => {
    return { results: [`Result for: ${args.query}`] };
  },
});

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

const result = await agent.run('Find info about serverless pricing');
console.log(result.text);
// "Serverless pricing typically follows a pay-per-use model..."

Agent Configuration

interface AgentConfig {
  router: Router;                    // Required: LLM router
  systemPrompt: string;              // Required: system instructions

  tools?: Tool[];                    // Optional: agent tools
  guard?: Guard;                     // Optional: budget guard
  maxIterations?: number;            // Default: 10
  onIteration?: (msg: string) => void;
  onToolCall?: (tool: string, args: object) => void;
  onComplete?: (result: AgentResult) => void;
}

AgentResult

interface AgentResult {
  text: string;           // Final response
  toolsUsed: string[];    // Tools called
  iterations: number;     // Loop iterations
  latencyMs: number;      // Total time
  costUsd: number;        // Estimated cost
  toolResults: object[];  // Raw tool outputs
}