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
- If tool names change in packages/…/*.ts, update packages/…/system.ts, packages/…/context7.ts, and packages/…/index.test.ts together: the agent prompt instructs the model to call literal tool names, the agent registers literal keys, and tests assert those names in tool-call traces.
- If the Context7 SDK changes
searchLibraryorgetContextresponse defaults or options, verify packages/…/resolve-library-id.ts and packages/…/query-docs.ts: both explicitly request{ type: "txt" }to keep AI SDK tool outputs LLM-readable even though the SDK may default to another format. - If path aliases change in packages/…/tsconfig.json, also update packages/…/tsup.config.ts and packages/…/vitest.config.ts; build, declaration generation, and tests each configure
@tools,@agents, and@promptsseparately rather than sharing a generated alias map. - If public exports are added or moved in packages/…/index.ts or src/…/index.ts, keep packages/…/package.json and packages/…/tsup.config.ts aligned: the package has a root export and a
./agentexport, and tsup only emits entries namedindexandagent. - If
Context7ToolsConfigin packages/…/types.ts gains configuration beyondapiKey, thread it through packages/…/context7.ts; the agent currently builds onecontext7Configand passes it to both tool factories.
Risks
- packages/…/README.md documents older names (
resolveLibrary,getLibraryDocs) while the actual exports in packages/…/index.ts areresolveLibraryIdandqueryDocs; 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_KEYand 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.