@upstash/agentkit-eve

• userId (required) — a string, or (input, ctx) => string.
• topK — max memories recall returns.
• minScore — BM25 relevance floor.
• redis — defaults to Redis.fromEnv().

userId is the only tenant boundary (required, non-empty, no :). Derive it from eve's verified session auth — ctx.session.auth.current?.principalId — not from anything the client supplies. Configure a real authenticator (vercelOidc(), an OIDC/JWT provider like Clerk, …) so principalId is trustworthy; the ?? ctx.session.id fallback only applies to unauthenticated requests. Memories are stored at agentkit:memory:<userId>:<id>.

• schema (required) — built with s from @upstash/redis.
• indexName — defaults to "agentkit:search"; ties all three tools to one index.
• prefix — key prefix for indexed JSON docs (defaults to "<indexName>:").
• defaultLimit — default page size for search (10).
• redis — defaults to Redis.fromEnv().

Each tool file must be self-contained, so call defineSearchTools in each one and export the member you want — repeat the same schema + indexName across search_books.ts / aggregate_books.ts / count_books.ts. The index is created reactively on first use, and each returned tool is already defineTool-branded.

• limiter (required) — e.g. Ratelimit.slidingWindow(20, "1 m") or fixedWindow(...).
• identifier (required) — a string, or (request) => string. There's no implicit "global": one shared bucket lets a single abusive caller exhaust the window for everyone, so derive it per request (an auth user id, an API key, or x-forwarded-for for per-IP).
• prefix — base key prefix; keys are <prefix>:<identifier> (default agentkit:rateLimit).
• message — 403 body when over the limit.
• redis — defaults to Redis.fromEnv().

It's a gate: under the limit it returns null to fall through to the next AuthFn; over it throws a 403.

eve runs each turn as two authenticated requests: the message POST (which invokes the model) and a follow-up GET …/stream that opens the reply stream. The auth walk runs on both, so counting both would charge every turn twice. createRateLimitAuth counts only the POSTs, so one turn costs one token: a Ratelimit.slidingWindow(20, "1 m") allows 20 turns per minute, not 10. The session-read GETs pass through unthrottled.

upstash(config) takes the @upstash/box BoxConfig verbatim — whatever you'd pass to Box.create({...}): runtime, size, apiKey (defaults to UPSTASH_BOX_API_KEY), keepAlive, initCommand, env, skills, mcpServers, timeout, … — plus an optional redis (defaults to Redis.fromEnv()). networkPolicy is not a config knob (see below).

@upstash/box is an optional peer dependency — only needed when you import @upstash/agentkit-eve/sandbox.

The sandbox runs untrusted, model-generated code, so open egress would mean SSRF / data exfiltration / reaching your own infrastructure from inside the box. Open it per-session — in bootstrap's use(...) or the session use(...) — never as a config knob. Note that env passed to upstash({ env }) is readable by code running in the box; don't pass secrets you wouldn't want it to see.

Box network policies are plain domain/CIDR allow-lists. Eve's per-domain firewall rules (transform header injection, forwardURL) have no Box equivalent, so passing them in use({ networkPolicy }) throws rather than silently sending the request unauthenticated:

// ❌ throws — Box can't inject headers via a per-session policy
export default defineSandbox({
  backend: upstash({ runtime: "node" }),
  async onSession({ use }) {
    await use({
      networkPolicy: {
        allow: { "api.example.com": [{ transform: [{ headers: { authorization: "Bearer …" } }] }] },
      },
    });
  },
});

Broker credentials with Box's attachHeaders instead (set at backend creation; a proxy on the box injects them), and open the domain with a plain allow-list:

// ✅ headers injected at the firewall; the secret never enters the box
export default defineSandbox({
  backend: upstash({
    runtime: "node",
    attachHeaders: { "api.example.com": { Authorization: "Bearer …" } },
  }),
  async onSession({ use }) {
    await use({ networkPolicy: { allow: ["api.example.com"] } });
  },
});

Reuse — eve re-opens a session several times per turn; the backend reattaches to the same Box instead of creating a new one each time. Boxes default to Box's pause-based idle lifecycle (keepAlive: false) — auto-paused when idle, resumed on reattach, reaped by Box. Pass keepAlive: true only for an always-running box you manage yourself.

Template registry — eve builds your template (seed files + bootstrap) at build/startup, but session creation runs per request in a different process, so the snapshot id is stored in a durable Redis registry (redis, defaulting to Redis.fromEnv()). Eve roots its tools at /workspace while a Box session lives at /workspace/home; the backend bridges the two automatically.

• description / inputSchema / execute — the usual defineTool fields; execute's result is memoized.
• toolName (required) — the tool segment of the cache key.
• userId (required) — a string, or (input, ctx) => string; scopes the cache per user.
• ttlSeconds — per-result TTL (default: no expiry).
• redis — defaults to Redis.fromEnv().

Keys are agentkit:toolCache:<userId>:<toolName>:<hash>.