Agentify/Developer Hub
GitHubGet API Key

Integration Guide

Learn how to integrate Agentify API into your AI agent in 15 minutes

📋 Table of Contents

🎯 Why Agentify?

In the Zero-Click Economy, AI agents are the new gatekeepers. Users ask questions, AI agents find answers—often without users ever clicking a link. If your products aren't AI-discoverable, they're invisible.

❌ The Problem

  • Generic product descriptions don't match AI agent queries
  • No trust signals → AI agents skip your products
  • Missing semantic tags → Poor intent matching
  • Inconsistent data → AI can't make recommendations

✅ The Agentify Solution

  • Multi-Agent Validation: Every product audited by 3 LLMs (Gemini, Claude, ChatGPT)
  • Transparent Trust Scores: 0-1 score with detailed breakdown (extraction, audit, human verification)
  • Semantic Tags: Product specialty, user profiles, decision hints
  • Decision-Ready Format: Pre-structured for AI consumption, no post-processing
  • GPC Taxonomy: Standardized classification aligned with global standards

🏗️ Cost-Transfer Architecture

Unlike traditional search APIs, Agentify uses a cost-efficient architecture where you compute embeddings once, and we handle all the infrastructure complexity.

💡 Economic Model: You Pay for Embeddings, We Handle the Rest

Your Side (One-Time Cost)

  • ✓ Generate embedding vector
  • ✓ ~$0.00002 per query (OpenAI text-embedding-3-small)
  • ✓ Can cache for identical queries

Our Side (Infrastructure)

  • ✓ Qdrant vector database
  • ✓ Hybrid filtering engine
  • ✓ Multi-agent validation system
  • ✓ Semantic enrichment pipeline

Result: You save on infrastructure costs while getting production-grade search capabilities and validated data.

📊 Architecture Flow

┌─────────────────┐
│  Your AI Agent  │
└────────┬────────┘
         │ 1. User query: "eco-friendly water bottle"
         ▼
┌─────────────────────────────┐
│  Embedding Model (OpenAI)  │  ← You compute this
└────────┬────────────────────┘
         │ 2. Vector [0.023, -0.145, 0.891, ...]
         ▼
┌─────────────────────────────┐
│   POST /vector-search       │
│   { q_vector: [...] }       │  ← Agentify API
└────────┬────────────────────┘
         │ 3. Semantic search + Multi-agent validation
         ▼
┌─────────────────────────────┐
│  Decision-Ready DPPAs       │
│  with trust scores 0.85+    │  ← AI-consumable format
└─────────────────────────────┘

⚡ 5-Minute Quickstart

Step 1: Install OpenAI SDK

npm install openai

Step 2: Test with Example Query

import OpenAI from 'openai';

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

async function searchProducts(query: string) {
  // 1. Generate embedding from user query
  const embedding = await openai.embeddings.create({
    model: "text-embedding-3-small",
    input: query,
  });

  // 2. Search Agentify with the vector
  const response = await fetch('https://agentify-v3.vercel.app/api/dpp/v1/vector-search', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      q_vector: embedding.data[0].embedding,
      limit: 10,
      filter: {
        minTrustScore: 0.7  // Only high-quality products
      }
    })
  });

  const results = await response.json();
  return results;
}

// Try it!
const products = await searchProducts("eco-friendly portable water bottle for hiking");
console.log(products.results);

✅ You're done!

You now have semantic product search with AI-validated data and trust scores.

🧠 Generating Embeddings

Agentify expects 1536-dimensional vectors from OpenAI's text-embedding-3-small model. This is the same model we use internally, ensuring semantic alignment.

⚠️ Important: Use the Same Model

Different embedding models create incompatible vector spaces. Always use text-embedding-3-small for best results.

Supported Platforms

Node.js / TypeScript

import OpenAI from 'openai';
const client = new OpenAI();
const emb = await client.embeddings.create({
  model: "text-embedding-3-small",
  input: query
});

Python

from openai import OpenAI
client = OpenAI()
response = client.embeddings.create(
  model="text-embedding-3-small",
  input=query
)

💰 Cost Optimization

  • Cache embeddings for identical queries (Redis, in-memory)
  • Batch similar queries together
  • ~$0.00002 per request with text-embedding-3-small
  • Much cheaper than running your own vector database

📚 Using the Dictionary

The dictionary is your semantic contract with Agentify. It defines the official vocabulary, taxonomies, and scoring rules.

Discovering Valid Tags

GET /api/dpp/v1/meta/dictionary

// Response includes:
{
  "tags": {
    "ai:productSpecialty": [
      {
        "tag": "EcofriendlyDesign",
        "synonyms": ["eco", "sustainable", "green"],
        "usageCount": 23
      },
      ...
    ]
  },
  "metrics": {
    "ai:trustScore": {
      "description": "Overall quality score (0-1)",
      "components": [
        { "name": "sourceExtraction", "weight": 0.2 },
        { "name": "sourceAudit", "weight": 0.3 },
        ...
      ]
    }
  }
}

Fuzzy Search for Tags

GET /api/dpp/v1/meta/dictionary?search=urban

// Finds: "UrbanStyle" and all synonyms
{
  "query": "urban",
  "results": [
    {
      "tag": "UrbanStyle",
      "synonyms": ["urban_style", "street", "city_wear"],
      "usageCount": 15
    }
  ]
}

🔄 Dynamic Growth

The dictionary grows as the catalog expands. Check /api/dpp/v1/meta/dictionary/statsto see new tags and trending products.

💻 Complete Code Examples

Example 1: E-Commerce Chatbot

// Scenario: User asks "I need a gift for an eco-conscious runner"

import OpenAI from 'openai';

const openai = new OpenAI();

async function findGiftForRunner(userMessage: string) {
  // 1. Generate embedding
  const embedding = await openai.embeddings.create({
    model: "text-embedding-3-small",
    input: userMessage
  });

  // 2. Search with semantic + profile filters
  const response = await fetch('/api/dpp/v1/vector-search', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      q_vector: embedding.data[0].embedding,
      limit: 5,
      filter: {
        minTrustScore: 0.8,  // High quality only
        category: "Sports & Outdoors"
      }
    })
  });

  const { results } = await response.json();

  // 3. Filter by semantic tags
  const ecoRunnerProducts = results.filter(r => 
    r.dppa['agentify:matching.userProfile'].includes('eco_conscious') &&
    r.dppa['agentify:matching.userProfile'].includes('sportifs_actifs')
  );

  return ecoRunnerProducts;
}

// Returns products like:
// - Biodegradable Running Water Bottle
// - Eco-Friendly Athletic Socks
// - Sustainable Fitness Tracker

Example 2: Product Recommendation Engine

// Scenario: Recommend complementary products

async function getComplementaryProducts(productId: string) {
  // 1. Get original product
  const product = await fetch(`/api/dpp/v1/full-dpp/${productId}`)
    .then(r => r.json());

  // 2. Use its tags to find similar
  const tags = product['ai:productSpecialty'].join(' ');
  
  const embedding = await openai.embeddings.create({
    model: "text-embedding-3-small",
    input: tags
  });

  // 3. Search with same category
  const results = await fetch('/api/dpp/v1/vector-search', {
    method: 'POST',
    body: JSON.stringify({
      q_vector: embedding.data[0].embedding,
      filter: {
        category: product.category,
        minTrustScore: 0.7
      }
    })
  }).then(r => r.json());

  return results.results.filter(r => r.id !== productId);
}

✅ Best Practices

1. Always Filter by Trust Score

Use minTrustScore: 0.7 to ensure high-quality results. Scores below 0.5 may have incomplete or unvalidated data.

2. Cache Embeddings

Identical queries produce identical embeddings. Cache them to save costs.

const cache = new Map();
if (cache.has(query)) return cache.get(query);
const emb = await generateEmbedding(query);
cache.set(query, emb);

3. Use Hybrid Filtering

Combine semantic search with hard filters (category, price) for better precision.

4. Check Dictionary Regularly

New tags are added as the catalog grows. Query /meta/dictionary/statsto discover trending products and emerging categories.

5. Handle Empty Results

If no results match, relax filters (lower minTrustScore, remove category) and re-query with broader criteria.

Ready to Make Your Products AI-Discoverable?

Start building with Agentify API today. Full OpenAPI spec available.

📖 View API Docs📥 Download OpenAPI Spec💬 Contact Support