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