> ## Documentation Index
> Fetch the complete documentation index at: https://context7.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Context7Agent

> Pre-built AI agent for documentation lookup workflows

The `Context7Agent` class is a pre-configured AI agent that handles the complete documentation lookup workflow automatically. It combines both `resolveLibraryId` and `queryDocs` tools with an optimized system prompt.

## Usage

```typescript theme={null}
import { Context7Agent } from "@upstash/context7-tools-ai-sdk";
import { anthropic } from "@ai-sdk/anthropic";

const agent = new Context7Agent({
  model: anthropic("claude-sonnet-5-5"),
});

const { text } = await agent.generate({
  prompt: "How do I use React Server Components?",
});

console.log(text);
```

## Configuration

```typescript theme={null}
new Context7Agent(config: Context7AgentConfig)
```

### Parameters

**config** `Context7AgentConfig` *required*

Configuration options for the agent.

**properties**

**model** `LanguageModel` *required*

Language model to use. Must be a LanguageModel instance from an AI SDK provider.

Examples:

* `anthropic('claude-sonnet-5-5')`
* `openai('gpt-6-astra')`
* `google('gemini-3.8-flash')`

**apiKey** `string`

Context7 API key. If not provided, uses the `CONTEXT7_API_KEY` environment variable.

**instructions** `string`

Custom system prompt. Overrides the default `AGENT_PROMPT`.

**stopWhen** `StopCondition` (default: stepCountIs(5))

Condition for when the agent should stop. Defaults to stopping after 5 steps.

### Returns

`Context7Agent` extends the AI SDK `ToolLoopAgent` class and provides `generate()` and `stream()` methods.

## Agent Workflow

The agent follows a structured multi-step workflow:

```mermaid theme={null}
flowchart TD
    A[User Query] --> B[Extract Library Name]
    B --> C[Call resolveLibraryId]
    C --> D{Results Found?}
    D -->|Yes| E[Select Best Match]
    D -->|No| F[Report No Results]
    E --> G[Call queryDocs]
    G --> H{Sufficient Context?}
    H -->|Yes| I[Generate Response]
    H -->|No| J[Fetch More Docs]
    J --> H
    I --> K[Return Answer with Examples]
```

### Step-by-Step

1. **Extract library name** - Identifies the library/framework from the user's query
2. **Resolve library** - Calls `resolveLibraryId` to find the Context7 library ID
3. **Select best match** - Analyzes results based on reputation, coverage, and relevance
4. **Fetch documentation** - Calls `queryDocs` with the selected library ID and user's query
5. **Query if needed** - Makes additional queries if initial context is insufficient
6. **Generate response** - Provides an answer with code examples from the documentation

## Examples

### Basic Usage

```typescript theme={null}
import { Context7Agent } from "@upstash/context7-tools-ai-sdk";
import { anthropic } from "@ai-sdk/anthropic";

const agent = new Context7Agent({
  model: anthropic("claude-sonnet-5-5"),
});

const { text } = await agent.generate({
  prompt: "How do I set up authentication in Next.js?",
});

console.log(text);
```

### With OpenAI

```typescript theme={null}
import { Context7Agent } from "@upstash/context7-tools-ai-sdk";
import { openai } from "@ai-sdk/openai";

const agent = new Context7Agent({
  model: openai("gpt-6-astra"),
});

const { text } = await agent.generate({
  prompt: "Explain Tanstack Query's useQuery hook",
});
```

### Streaming Responses

```typescript theme={null}
import { Context7Agent } from "@upstash/context7-tools-ai-sdk";
import { anthropic } from "@ai-sdk/anthropic";

const agent = new Context7Agent({
  model: anthropic("claude-sonnet-5-5"),
});

const { textStream } = await agent.stream({
  prompt: "How do I create a Supabase Edge Function?",
});

for await (const chunk of textStream) {
  process.stdout.write(chunk);
}
```

### Custom Configuration

```typescript theme={null}
import { Context7Agent } from "@upstash/context7-tools-ai-sdk";
import { anthropic } from "@ai-sdk/anthropic";
import { stepCountIs } from "ai";

const agent = new Context7Agent({
  model: anthropic("claude-sonnet-5-5"),
  apiKey: process.env.CONTEXT7_API_KEY,
  stopWhen: stepCountIs(8), // Allow more steps for complex queries
});
```

### Custom System Prompt

```typescript theme={null}
import { Context7Agent, AGENT_PROMPT } from "@upstash/context7-tools-ai-sdk";
import { openai } from "@ai-sdk/openai";

const agent = new Context7Agent({
  model: openai("gpt-6-astra"),
  instructions: `${AGENT_PROMPT}

Additional instructions:
- Always include TypeScript examples
- Mention version compatibility when relevant
- Suggest related documentation topics`,
});
```

## Comparison: Agent vs Tools

| Feature | Context7Agent | Individual Tools |
| - | - | - |
| Setup | Single configuration | Configure each tool |
| Workflow | Automatic multi-step | Manual orchestration |
| System prompt | Optimized default | You provide |
| Customization | Limited | Full control |
| Best for | Quick integration | Custom workflows |

### When to Use the Agent

* Rapid prototyping
* Standard documentation lookup use cases
* When you want sensible defaults

### When to Use Individual Tools

* Custom agentic workflows
* Integration with other tools
* Fine-grained control over the process
* Custom system prompts with specific behavior

## Related

* [resolveLibraryId](https://context7.com/docs/agentic-tools/ai-sdk/tools/resolve-library-id.md) - The library search tool used by the agent
* [queryDocs](https://context7.com/docs/agentic-tools/ai-sdk/tools/query-docs.md) - The documentation fetch tool used by the agent
* [Getting Started](https://context7.com/docs/agentic-tools/ai-sdk/getting-started.md) - Overview of the AI SDK integration


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.