Conversational Agent

{
  "userId": "clxyz1234567890",
  "message": "I need a hydrating serum under $50, no parabens",
  "config": {
    "persona": {
      "name": "Scout",
      "vertical": "skincare",
      "tone": "warm and knowledgeable"
    },
    "rules": [
      "Always check the user's avoidance list before recommending",
      "Include price in every product mention"
    ],
    "enabledTools": ["search_products", "get_recommendations", "record_interaction"],
    "maxHistory": 20
  }
}

{
  "message": "I found some great options for you! Based on your dry skin and hydration focus, here are my top picks...",
  "products": [
    {
      "id": "clprod_abc123",
      "name": "Hyaluronic Acid Serum",
      "brand": "The Ordinary",
      "price": 12.99,
      "currency": "USD",
      "imageUrl": "https://cdn.example.com/ha-serum.jpg",
      "productUrl": "https://example.com/products/ha-serum"
    }
  ],
  "profileUpdated": true,
  "orderInitiated": false
}

async function chatWithAgent(userId: string, message: string) {
  const response = await fetch(
    "https://api.podium.build/api/v1/companion/agent/chat/stream",
    {
      method: "POST",
      headers: {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ userId, message }),
    }
  );

  const reader = response.body!.getReader();
  const decoder = new TextDecoder();
  let buffer = "";

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    buffer += decoder.decode(value, { stream: true });
    const lines = buffer.split("\n");
    buffer = lines.pop()!;

    for (const line of lines) {
      if (line.startsWith("data: ")) {
        const event = JSON.parse(line.slice(6));

        switch (event.type) {
          case "text":
            process.stdout.write(event.content);
            break;
          case "tool_start":
            console.log(`\n[Using ${event.tool}...]`);
            break;
          case "tool_result":
            if (event.products?.length) {
              console.log(`\n[Found ${event.products.length} products]`);
            }
            break;
          case "memory_queued":
            console.log("[Memory extraction queued]");
            break;
          case "confirmation_required":
            console.log(`\nConfirm purchase: ${event.productName} (${event.productBrand}) — $${event.amount} ${event.currency}`);
            console.log(`Daily spend: $${event.spendSummary.dailySpent}/$${event.spendSummary.dailyLimit}`);
            break;
          case "spend_limit_exceeded":
            console.log(`\nSpend limit exceeded: ${event.reason}`);
            if (event.resetInfo) console.log(`Resets: ${event.resetInfo}`);
            break;
          case "done":
            if (event.quickReplies?.length) {
              console.log("\nSuggested replies:", event.quickReplies);
            }
            console.log("\n--- Complete ---");
            return event;
          case "error":
            throw new Error(event.error);
        }
      }
    }
  }
}

{
  "userId": "clxyz123",
  "message": "What should I try next?",
  "config": {
    "enabledTools": ["search_products", "get_recommendations"]
  }
}

{
  "config": {
    "persona": {
      "name": "Scout",
      "vertical": "skincare",
      "tone": "warm, knowledgeable, concise"
    },
    "rules": [
      "Never recommend products with parabens",
      "Always mention the user's skin type when giving advice",
      "If the user seems unsure, suggest a quiz to build their profile"
    ]
  }
}

{
  "type": "done",
  "message": "I found some great hydrating serums for you!",
  "products": [...],
  "quickReplies": ["Yes, show me serums", "What about moisturizers?", "Skip for now"]
}

GET /api/v1/companion/agent/chat/history/:userId?limit=50&before=cursor_id

[
  {
    "id": "msg_abc123",
    "role": "user",
    "content": "I need a hydrating serum under $50",
    "timestamp": "2026-03-18T14:30:00Z"
  },
  {
    "id": "msg_abc124",
    "role": "assistant",
    "content": "I found some great options for you!",
    "timestamp": "2026-03-18T14:30:02Z",
    "products": [...]
  }
]

{
  "type": "confirmation_required",
  "productId": "prod_abc123",
  "productName": "Hyaluronic Acid Serum",
  "productBrand": "The Ordinary",
  "amount": 12.99,
  "currency": "USD",
  "imageUrl": "https://cdn.example.com/ha-serum.jpg",
  "spendSummary": {
    "dailySpent": 45.00,
    "dailyLimit": 100.00,
    "txMax": 200.00
  }
}

{
  "userId": "clxyz1234567890",
  "message": "__greeting__",
  "config": {
    "greeting": true
  }
}

import { createPodiumClient } from "@podium-sdk/node-sdk";

const client = createPodiumClient({ apiKey: "podium_live_..." });

// 1. Create a user with an intent profile
const user = await client.user.create({
  requestBody: { email: "jane@example.com" },
});

await client.companion.createProfile({
  userId: user.id,
  requestBody: {
    skinType: "DRY",
    concerns: ["HYDRATION", "ANTI_AGING"],
    priceRange: { min: 10, max: 75 },
    avoidances: ["parabens", "sulfates"],
  },
});

// 2. Start a conversation
const response = await fetch(
  "https://api.podium.build/api/v1/companion/agent/chat",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      userId: user.id,
      message: "What serums should I try for winter dryness?",
      config: {
        persona: {
          name: "Scout",
          vertical: "skincare",
          tone: "friendly and expert",
        },
      },
    }),
  }
);

const result = await response.json();
console.log(result.message);
console.log(`Products found: ${result.products?.length ?? 0}`);

// 3. Follow up — the agent remembers the conversation
const followUp = await fetch(
  "https://api.podium.build/api/v1/companion/agent/chat",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      userId: user.id,
      message: "I like the first one. Can you order it for me?",
    }),
  }
);

const orderResult = await followUp.json();
if (orderResult.orderInitiated) {
  console.log(`Order created: ${orderResult.orderId}`);
}