Skip to main content

Overview

Agent Hints are pre-formatted strings optimized for AI context injection. They summarize user preferences in natural language, making it easy to include in system prompts.

Get Agent Hints

domains
string
Comma-separated list of domains to include
max_tokens
number
default:"100"
Maximum token count for hints
format
string
default:"text"
Output format: text, json, or bullets
curl -X GET "https://api.prefid.dev/v1/agent-hints?domains=music_preferences,food_profile&max_tokens=100" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Format Options

Text Format (Default)

Returns hints as a list of natural language strings.
GET /v1/agent-hints?format=text
{
  "hints": [
    "User loves AR Rahman and Indian classical music",
    "Prefers vegetarian food"
  ]
}

JSON Format

Returns structured hint data.
GET /v1/agent-hints?format=json
{
  "hints": {
    "music_preferences": {
      "summary": "Loves AR Rahman and Indian classical music",
      "top_artists": ["AR Rahman", "Coldplay"],
      "genres": ["Indian Classical", "Electronic"]
    },
    "food_profile": {
      "summary": "Vegetarian, allergic to peanuts",
      "dietary": "vegetarian",
      "allergies": ["peanuts"]
    }
  }
}

Bullets Format

Returns hints as markdown bullet points.
GET /v1/agent-hints?format=bullets
{
  "hints": "- Loves AR Rahman and Indian classical music\n- Uses Spotify for streaming\n- Vegetarian diet\n- Allergic to peanuts"
}

Context-Aware Hints

Get hints tailored for a specific context.
context
string
Context for hint generation (e.g., music_recommendation, restaurant_search)
curl -X GET "https://api.prefid.dev/v1/agent-hints?context=music_recommendation" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Using Agent Hints

In System Prompts

const hints = await fetch('/v1/agent-hints?domains=music_preferences');
const hintsData = await hints.json();

const systemPrompt = `
You are a music recommendation assistant.

User Context:
${hintsData.data.hints.join('\n')}

Based on these preferences, provide personalized recommendations.
`;

With Vercel AI SDK

import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

const hints = await prefid.getAgentHints({
  domains: ['music_preferences'],
  maxTokens: 50
});

const result = await generateText({
  model: openai('gpt-4'),
  system: `User preferences: ${hints.data.hints.join('. ')}`,
  prompt: 'Recommend 5 songs for a road trip'
});

Token Optimization

Agent hints are designed to be token-efficient. Use max_tokens to control the size:
max_tokensHint Detail
50Very brief (1-2 hints)
100Standard (3-5 hints)
200Detailed (5-10 hints)
500Comprehensive
Start with max_tokens=100 and adjust based on your context window needs.