Agent skill
Convex Agents Context
Customizes what information the LLM receives for each generation. Use this to control message history, implement RAG context injection, search across threads, and provide custom context.
Install this agent skill to your Project
npx add-skill https://github.com/Sstobo/convex-skills/tree/main/convex-agents-context
SKILL.md
Purpose
By default, the Agent includes recent messages as context. This skill covers customizing that behavior for advanced patterns like cross-thread search, memory injection, summarization, and filtering.
When to Use This Skill
- Limiting context window to prevent token overflow
- Searching across multiple threads for relevant context
- Injecting memories or user profiles into every prompt
- Summarizing long conversations before continuing
- Filtering out sensitive or irrelevant messages
- Adding few-shot examples to guide LLM
Configure Default Context Options
const myAgent = new Agent(components.agent, {
name: "My Agent",
languageModel: openai.chat("gpt-4o-mini"),
contextOptions: {
recentMessages: 50,
excludeToolMessages: true,
searchOptions: {
limit: 10,
textSearch: true,
vectorSearch: false,
},
},
});
Override Context Per Call
export const generateWithCustomContext = action({
args: { threadId: v.string(), prompt: v.string() },
handler: async (ctx, { threadId, prompt }) => {
const result = await myAgent.generateText(
ctx,
{ threadId },
{ prompt },
{
contextOptions: {
recentMessages: 20,
searchOptions: {
limit: 5,
textSearch: true,
vectorSearch: true,
},
},
}
);
return result.text;
},
});
Search Across Threads
export const generateWithCrossThreadContext = action({
args: { threadId: v.string(), userId: v.string(), prompt: v.string() },
handler: async (ctx, { threadId, userId, prompt }) => {
const result = await myAgent.generateText(
ctx,
{ threadId, userId },
{ prompt },
{
contextOptions: {
searchOtherThreads: true,
searchOptions: {
limit: 15,
textSearch: true,
vectorSearch: true,
},
},
}
);
return result.text;
},
});
Custom Context Handler
Completely customize context:
const myAgent = new Agent(components.agent, {
name: "My Agent",
languageModel: openai.chat("gpt-4o-mini"),
contextHandler: async (ctx, args) => {
const userMemories = await getUserMemories(ctx, args.userId);
const examples = getExamples();
return [
...userMemories,
...examples,
...args.search,
...args.recent,
...args.inputMessages,
];
},
});
Fetch Context Manually
Get context without calling LLM:
import { fetchContextWithPrompt } from "@convex-dev/agent";
export const getContextForPrompt = action({
args: { threadId: v.string(), prompt: v.string() },
handler: async (ctx, { threadId, prompt }) => {
const { messages } = await fetchContextWithPrompt(ctx, components.agent, {
threadId,
prompt,
contextOptions: {
recentMessages: 20,
searchOptions: { limit: 10, textSearch: true },
},
});
return messages;
},
});
Key Principles
- Default context is sufficient: Most use cases work with defaults
- Search improves relevance: Enable for long conversations
- userId required for cross-thread: Provide when searching multiple threads
- Context handlers are powerful: Use for memories, examples, special formatting
- Recent messages take precedence: Used after search in context order
Next Steps
- See rag for knowledge base context injection
- See fundamentals for agent setup
- See rate-limiting for token management
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
Sstobo/convex-skills
Convex Agents Streaming
Streams agent responses in real-time to clients without blocking. Use this for responsive UIs, long-running generations, and asynchronous streaming to multiple clients.
Sstobo/convex-skills
Convex Agents Files
Handles file uploads, image attachments, and media processing in agent conversations. Use this when agents analyze images, process documents, or generate files.
Sstobo/convex-skills
convex-actions-general
This skill should be used when working with Convex actions, HTTP endpoints, validators, schemas, environment variables, scheduling, file storage, and TypeScript patterns. It provides comprehensive guidelines for function definitions, API design, database limits, and advanced Convex features.
Sstobo/convex-skills
betterauth-tanstack-convex
Step-by-step guide for setting up Better Auth authentication with Convex and TanStack Start. This skill should be used when configuring authentication in a Convex + TanStack Start project, troubleshooting auth issues, or implementing sign up/sign in/sign out flows. Covers installation, environment variables, SSR authentication, route handlers, and the expectAuth pattern.
Sstobo/convex-skills
Convex Agents Tools
Enables agents to call external functions, APIs, and database operations through tool definitions. Use this when agents need to fetch data, perform actions, or integrate with external services while maintaining clean separation.
Sstobo/convex-skills
convex-queries
This skill should be used when implementing Convex query functions. It provides comprehensive guidelines for defining, registering, calling, and optimizing queries, including pagination, full text search, and indexing patterns.
Didn't find tool you were looking for?