Goal

Instrument a Tinkuy agent with Qhaway observability, expose Prometheus metrics, and visualize in Grafana.

Step 1: Install Dependencies

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

Step 2: Instrument the Agent

import { Agent, defineTool } from '@carloscortezcloud/tinkuy-agent';
import { StyrRouter } from '@carloscortezcloud/styrr-llm';
import { QhawayTrace, ConsoleStorage } from '@carloscortezcloud/qhaway/trace';
import { QhawayTinkuyPlugin } from '@carloscortezcloud/qhaway/tinkuy';
import { serveMetrics } from '@carloscortezcloud/qhaway';

// Setup observability
const trace = new QhawayTrace(new ConsoleStorage(), {
  agent_id: 'observed-agent',
});

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

// Create agent with hooks
const agent = new Agent({
  router: new StyrRouter({
    apiKey: process.env.OPENROUTER_API_KEY,
    models: [{ id: 'nvidia/nemotron-3-ultra-550b:free' }],
  }),
  tools: [/* ... */],
  systemPrompt: 'You are a helpful assistant.',
  onIteration: (e) => plugin.hooks.onIteration(e),
  onToolCall: (e) => plugin.hooks.onToolCall(e),
  onComplete: (e) => plugin.hooks.onComplete(e),
});

// Serve Prometheus metrics
const { server } = serveMetrics({ port: 9090 });

// Run agent
const result = await agent.run('Analyze our AWS costs');

Step 3: Configure Prometheus

# prometheus.yml
scrape_configs:
  - job_name: 'agents'
    static_configs:
      - targets: ['localhost:9090']

Step 4: Grafana Dashboard

Import the Qhaway dashboard and connect Prometheus:

1. Grafana → + → Import
2. Load JSON from @carloscortezcloud/qhaway/src/dashboard/qhaway-dashboard.json
3. Set Prometheus as data source

What You See

• Cost per model — which models are spending
• Latency P99 — response time trends
• Call volume — requests per minute by model
• Cost per user — who’s spending the most
• Error rate — failed calls percentage

Production Setup

For production, use D1 or KV storage instead of MemoryStorage, and point Prometheus to your Worker’s metrics endpoint.