Overview

Tinkuy provides three observability hooks. They fire during the agent loop without coupling to any specific monitoring tool.

onIteration

Called after each LLM call in the loop. Receives the assistant’s response message.

const agent = new Agent({
  router,
  tools: [myTool],
  systemPrompt: '...',
  onIteration: (msg) => {
    console.log(`[Iteration] ${msg.slice(0, 100)}...`);
  },
});

onToolCall

Called when the LLM invokes a tool. Receives the tool name and arguments.

const agent = new Agent({
  router,
  tools: [myTool],
  systemPrompt: '...',
  onToolCall: (tool, args) => {
    console.log(`[Tool] ${tool}(${JSON.stringify(args)})`);

    // Send to observability
    await fetch('https://api.honeycomb.io/v1/traces', {
      method: 'POST',
      body: JSON.stringify({
        tool,
        args,
        timestamp: new Date().toISOString(),
      }),
    });
  },
});

onComplete

Called when the agent finishes with the final result.

const agent = new Agent({
  router,
  tools: [myTool],
  systemPrompt: '...',
  onComplete: (result) => {
    console.log('[Complete]', {
      iterations: result.iterations,
      toolsUsed: result.toolsUsed,
      costUsd: result.costUsd,
      latencyMs: result.latencyMs,
    });

    // Store in database
    await db.insertAgentRun({
      timestamp: new Date(),
      iterations: result.iterations,
      cost: result.costUsd,
      success: true,
    });
  },
});

Integration with Qhaway

For full observability, use the Qhaway Tinkuy plugin which connects all three hooks to structured storage + OTEL + Grafana:

import { QhawayTrace, ConsoleStorage } from '@carloscortezcloud/qhaway/trace';
import { QhawayTinkuyPlugin } from '@carloscortezcloud/qhaway/tinkuy';

const plugin = new QhawayTinkuyPlugin({
  storage: new ConsoleStorage(),
  agentName: 'my-agent',
});

const agent = new Agent({
  router,
  tools: [myTool],
  systemPrompt: '...',
  onIteration: (e) => plugin.hooks.onIteration(e),
  onToolCall: (e) => plugin.hooks.onToolCall(e),
  onComplete: (e) => plugin.hooks.onComplete(e),
});