Introducing a new way to review your PRs.

Read the announcement

upstash / context7

Context7 Platform -- Up-to-date docs for AI agents

View on GitHub

13 documents · Updated Nov 16, 2026

docs / tools-ai-sdk

Tools AI SDK Integration Package

Overview

packages/tools-ai-sdk publishes @upstash/context7-tools-ai-sdk, a small integration layer that turns the Context7 SDK into Vercel AI SDK tools and a pre-wired agent. The public root export in packages/…/index.ts exposes the agent (Context7Agent), the two tool factories (resolveLibraryId, queryDocs), prompt strings, and selected types from @upstash/context7-sdk.

The tool factories live under packages/tools-ai-sdk/src/tools/. src/…/resolve-library-id.ts returns an AI SDK tool() with a Zod input schema requiring query and libraryName; at execution time it constructs new Context7({ apiKey }) and calls client.searchLibrary(query, libraryName, { type: "txt" }). Errors are caught and returned as strings, so callers receive an LLM-readable failure instead of a thrown exception. src/…/query-docs.ts has the same factory shape but requires libraryId and query, calls client.getContext(query, libraryId, { type: "txt" }), and converts empty results or Context7Error 404s into a “No documentation found” message that tells the agent to run resolveLibraryId again. Both factories accept Context7ToolsConfig from src/…/types.ts; today that config only carries an optional apiKey, falling back to the Context7 SDK’s CONTEXT7_API_KEY environment handling when absent.

Prompt text is centralized in packages/…/system.ts and re-exported through src/…/index.ts. AGENT_PROMPT is the default instruction set for the bundled agent and explicitly orders the model to call resolveLibraryId before queryDocs, select the best official/high-reputation library ID, limit tool calls, and cite the selected library ID. The tool descriptions exported from the same file are passed directly into the AI SDK tool definitions in src/…/resolve-library-id.ts and src/…/query-docs.ts, so prompt wording changes immediately affect runtime tool-selection behavior.

packages/…/context7.ts defines Context7Agent, extending AI SDK ToolLoopAgent<never, ToolSet>. Its constructor pulls model, optional stopWhen, optional instructions, optional apiKey, and optional caller-provided tools out of Context7AgentConfig; it defaults stopWhen to stepCountIs(5) and instructions to AGENT_PROMPT. It merges caller tools first and then adds resolveLibraryId and queryDocs, meaning the Context7 tool names are always present on the final agent and override same-named custom tools. The package also exposes packages/…/index.ts as a secondary build entry for the ./agent package export.

Tests are concentrated in packages/…/index.test.ts. They check tool object shape, exercise generateText with forced resolveLibraryId and queryDocs tool choices, verify the two-tool multi-step flow, assert that Context7Agent includes both Context7 tools alongside custom tools, and assert prompt exports. These tests use @openrouter/ai-sdk-provider with OPENROUTER_API_KEY and actual Context7-backed executions, with 30–60 second timeouts for model calls.

Build and package metadata are in packages/…/package.json, tsup.config.ts, tsconfig.json, vitest.config.ts, and eslint.config.js. package.json publishes CJS/ESM/types from dist, exports both . and ./agent, and declares @upstash/context7-sdk, ai, and zod as peer dependencies. tsup.config.ts builds src/index.ts and src/…/index.ts to both CJS and ESM, generates declarations, and mirrors the TypeScript aliases @tools, @agents, and @prompts; tsconfig.json and vitest.config.ts define the same aliases for typecheck and tests. vitest.config.ts loads the repository root .env before running src/…/*.test.ts in Node.

Coupling

Risks

  • packages/…/README.md documents older names (resolveLibrary, getLibraryDocs) while the actual exports in packages/…/index.ts are resolveLibraryId and queryDocs; copying README examples will fail to compile unless the documentation is brought back in sync with the source.
  • packages/…/index.test.ts depends on live OpenRouter and Context7 behavior through OPENROUTER_API_KEY and real tool executions. Missing credentials, model/provider changes, or upstream response wording can fail tests even when packages/…/*.ts is unchanged.
  • packages/…/query-docs.ts and src/…/resolve-library-id.ts return error strings instead of throwing. This keeps agents conversational, but consumers and tests cannot rely on rejected promises for operational failures; if error handling is changed, downstream AI SDK flows may start surfacing exceptions instead of model-readable recovery instructions.
  • Recent package history shows repeated prompt and tool-contract patches under packages/tools-ai-sdk (33229cb, 1c081df, 615e72b, bdd9bf7). Treat wording changes in packages/…/system.ts and input descriptions in src/…/*.ts as behavior changes, not cosmetic edits, because they alter how models call the tools.