@socialseed/agent — Agent SDK Reference

Install

# Node 20+, ESM
npm i @socialseed/agent
# peer: nothing. zero UI deps. ~14 kB gzip.

Quickstart — hire a campaign

One call turns a product + a budget into a fully-run seeding campaign: strategy → creator sourcing → AI briefs (with mandatory #ad disclosure) → scheduled publishing → measurement → kill-and-scale reallocation. The agent stops when verified-views × $0.01 hits the deposit.

import { SocialSeed } from '@socialseed/agent';

const client = new SocialSeed({ apiKey: process.env.SOCIALSEED_KEY });

const campaign = await client.campaigns.hire({
  budget:  { deposit_usd: 500, hard_cap: true },        // → 50,000 verified views max
  product: { name: 'Cloud Slides', url: 'https://shop.example/slides',
             tiktok_shop_id: 'ts_88213', price_usd: 34 },
  market:  { regions: ['US'], creator_tier: 'micro' },     // 10k–100k followers
  guardrails: { disclosure: '#ad', community_guidelines: true }
});

console.log(campaign.id);          // "cmp_2f9a..." — A2A-addressable
console.log(campaign.status);      // "planning"
console.log(campaign.a2a_url);     // "https://a2a.socialseed.ing/agents/cmp_2f9a..."

Webhooks — verified-view event stream

Register one endpoint; the host app renders the rest. Every view passes a fraud filter (dedup, watch-time threshold, source-anomaly, attribution) before it bills.

// POST {your_webhook}  —  event: campaign.view.verified
{
  "event": "campaign.view.verified",
  "campaign_id": "cmp_2f9a3c",
  "post_id": "mocktt_post_5512",
  "creator": { "handle": "@reefwalks", "tier": "micro" },
  "view": {
    "dedup_id": "v_9f1c0a2e",
    "watch_time_s": 7.8,            // ≥ 5.0s threshold → counts
    "source": "fyp",
    "fraud_filter": { "verdict": "pass", "checks": ["dedup","watch_time","source_anomaly","attribution"] }
  },
  "billing": { "unit_usd": 0.01, "campaign_spent_usd": 312.47, "deposit_usd": 500.00 },
  "shop_click": true,                  // attributed click-through to TikTok Shop
  "ts": "2026-05-12T14:02:11Z"
}

// event: campaign.budget.exhausted  — agent halts all spend
{ "event": "campaign.budget.exhausted", "campaign_id": "cmp_2f9a3c",
  "verified_views": 50000, "spent_usd": 500.00, "gmv_attributed_usd": 6140.00 }

A2A agent card

Each hired campaign exposes itself as an A2A agent so the host's own orchestrator (or another vendor's agent) can converse with it directly.

// GET https://a2a.socialseed.ing/agents/cmp_2f9a3c/.well-known/agent.json
{
  "name": "socialseed-campaign-runner",
  "description": "Autonomous TikTok / TikTok Shop social-seeding campaign agent",
  "protocol": "a2a/0.2",
  "provider": { "organization": "SocialSeed.ing", "runtime": "Vertex AI Agent Engine" },
  "skills": [
    { "id": "strategy",          "name": "Plan seeding strategy from product + budget" },
    { "id": "source_creators",   "name": "Source & rank micro-creators" },
    { "id": "generate_briefs",   "name": "AI briefs/captions/storyboards w/ #ad disclosure" },
    { "id": "publish",           "name": "Schedule + publish (mock TikTok endpoint)" },
    { "id": "measure_reallocate","name": "Kill underperformers, scale winners" },
    { "id": "report_roi",        "name": "CPV / clicks / GMV report" }
  ],
  "capabilities": { "streaming": true, "pushNotifications": true },
  "authentication": { "schemes": ["bearer"], "scope": "campaign:cmp_2f9a3c" }
}

MCP tool manifest

Drop SocialSeed into your agent via MCP — the host's ADK agent calls these tools directly. No SocialSeed UI ever appears.

# mcp.json (host app)
{ "mcpServers": { "socialseed": {
    "command": "npx", "args": ["-y","@socialseed/mcp"],
    "env": { "SOCIALSEED_KEY": "${SOCIALSEED_KEY}" } } } }

Billing — usage / ledger endpoint

// GET /v1/campaigns/cmp_2f9a3c/ledger
{
  "campaign_id": "cmp_2f9a3c", "unit_usd": 0.01, "deposit_usd": 500.00,
  "lines": [
    { "date": "2026-05-10", "verified_views": 8120,  "amount_usd": 81.20 },
    { "date": "2026-05-11", "verified_views": 14955, "amount_usd": 149.55 },
    { "date": "2026-05-12", "verified_views": 8172,  "amount_usd": 81.72 }
  ],
  "rejected_views": 2310,   // failed fraud filter — never billed
  "running": { "verified_views": 31247, "spent_usd": 312.47, "remaining_usd": 187.53 }
}

Embed examples

Constraints baked in

ADK multi-agentA2A coordinationMCP tool surfaceGemini on Vertex AIAgent Engine runtimemock TikTok + metrics simulatorsynthetic creator pool$0.01/verified viewfraud filter: dedup · watch-time · source-anomaly · attributionhard budget cap (server-enforced)mandatory #ad disclosure in every briefno paid-ads / legal advice framing