Cache Tool Results

easy5 mintool-caching.ts

A tool calls a slow or paid API, and agents keep asking for the same thing. You want repeated calls served from a cache with a TTL.

What it shows

Wrap a tool with withCache() (exact matching, TTL, size limit)
Inspect hit rate, invalidate one entry, warm the cache up front

The code

tool-caching.ts

import { tool, withCache } from '@cogitator-ai/core';
import { z } from 'zod';

let apiCalls = 0;

const weatherLookup = tool({
  name: 'weather_lookup',
  description: 'Get current weather for a city',
  parameters: z.object({ city: z.string().describe('City name') }),
  execute: async ({ city }) => {
    apiCalls++;
    return { city, temperature: 12, condition: 'Overcast', fetchedAt: new Date().toISOString() };
  },
});

const cachedWeather = withCache(weatherLookup, {
  strategy: 'exact',
  ttl: '5m',
  storage: 'memory',
  maxSize: 50,
  onHit: (_key, params) => console.log('cache hit', params),
  onMiss: (_key, params) => console.log('cache miss', params),
});

const context = { agentId: 'demo', runId: 'cache-demo', signal: new AbortController().signal };

await cachedWeather.execute({ city: 'London' }, context);
await cachedWeather.execute({ city: 'London' }, context);
console.log('API calls:', apiCalls);

const stats = cachedWeather.cache.stats();
console.log(`hits=${stats.hits} misses=${stats.misses} hitRate=${(stats.hitRate * 100).toFixed(0)}%`);

await cachedWeather.cache.invalidate({ city: 'London' });
await cachedWeather.execute({ city: 'London' }, context);
console.log('API calls after invalidate:', apiCalls);

await cachedWeather.cache.warmup([
  {
    params: { city: 'Paris' },
    result: { city: 'Paris', temperature: 14, condition: 'Light Rain', fetchedAt: new Date().toISOString() },
  },
]);
const paris = await cachedWeather.execute({ city: 'Paris' }, context);
console.log(`Paris (from warmup): ${paris.temperature}°C, API calls still ${apiCalls}`);

await cachedWeather.cache.clear();

Run it

install · bash

pnpm add @cogitator-ai/core zod

run · bash

npx tsx tool-caching.ts

Or run the full example from a clone of the repository (keys in .env):

repository · bash

npx tsx examples/core/03-tool-caching.ts

Cache Tool Results

What it shows

The code

Run it

Learn more