TrendsAGI

TrendsAGI

为你的代码和 AI Agent 提供实时趋势情报：了解社交平台上当前的热门趋势，查看经过衡量的声量、速度和增长情况，以及每个话题热度变化背后的 AI 洞察、有证据支持的建议、危机提醒和监控列表。付费媒体和增长团队借助它锁定正在上升的话题，根据趋势曲线安排投放时机，并基于经过衡量的需求制定创意简报。

Python 客户端	TrendsAGIClient，一个带类型的 REST 客户端
命令行	trendsagi，每个 API 操作对应一条命令；在终端中显示表格，通过管道输出 JSON
Agent 工具	面向 OpenAI、Claude、LangChain 和 WebMCP 的 TrendsAGITools
托管 MCP 服务	https://api.trendsagi.com/mcp，适用于 Claude、ChatGPT、Grok、Cursor 和 Gemini CLI
浏览器 Agent（WebMCP）	登录 app.trendsagi.com 后，浏览器中的 Agent 即可使用相同的工具（webmcp/）
本地 MCP 服务	trendsagi mcp，通过 stdio 提供相同的工具
插件	plugins/trendsagi 中的 Claude、Grok 和 Cursor 插件，以及位于仓库根目录的 Gemini CLI 扩展
广告执行	执行器可从你自己的基础设施预览并应用 Google、Meta、TikTok 和 LinkedIn 广告更改

安装

pip install trendsagi            # client, agent tools and the trendsagi command
pip install "trendsagi[mcp]"     # adds the local MCP server (Python 3.10+)
pipx install trendsagi           # just the command line, in its own environment
npx trendsagi --help             # or the same command line from npm (Node.js 18+)

在 app.trendsagi.com 的 Profile > API Keys 下创建 API 密钥并将其导出：

export TRENDSAGI_API_KEY="your_api_key"

快速入门

import os
from trendsagi import TrendsAGIClient

client = TrendsAGIClient(api_key=os.environ["TRENDSAGI_API_KEY"])

# Fastest-moving Technology topics right now
trends = client.get_trends(category="Technology", sort_by="velocity", limit=5)
for trend in trends.trends:
    print(trend.id, trend.name, trend.volume)

# Why is the top one moving?
insight = client.get_ai_insights(trends.trends[0].id)
if insight:
    print(insight.sentiment_summary, insight.key_themes)

命令行

trendsagi login                  # paste an API key; saved to ~/.config/trendsagi/config.json
trendsagi trends list --category Technology --sort velocity --limit 10
trendsagi insights get 123       # audience, sentiment and marketing angles
trendsagi sql "SELECT category, count(*) FROM trends GROUP BY 1 ORDER BY 2 DESC"
trendsagi recommendations list --priority high
trendsagi watchlist add "oat milk" --threshold 50000 --email
trendsagi api /api/integrations/delivery/health -q lookback_hours=24   # any endpoint

命令	功能
login、logout、whoami	保存、忘记并检查 API 密钥
trends list get analytics categories autocomplete	查看经过衡量的声量、速度和增长情况的热门话题
insights get generate [--wait] status search	查看每个趋势的 AI 洞察
recommendations list action feedback	查看有证据支持的建议及其工作流状态
crisis list action	处理危机事件：确认、归档、重新打开
watchlist list add remove	监控关键词和类别并接收提醒
sql、schema	对你的数据执行只读 PostgreSQL SELECT 查询，并查看可读取的表
tools list call、find	查看 Agent 工具，以及 TrendsAGI 能否完成某项任务
webhooks、exports	创建、更改、测试和运行 Webhook 及数据导出
ads providers resources preview apply report report-export	已连接的广告平台：基于趋势进行更改并生成报告
integrations availability status health value	查看集成状态和交付健康状况
stream	以 JSON 行形式实时接收趋势更新
usage、status、api	查看 API 使用情况和服务状态，或调用没有专属命令的端点

每条命令都支持 --help。在终端中，列表以表格形式输出；通过管道传递或使用 --json 时则输出 JSON，因此可以运行 trendsagi trends list | jq。密钥依次取自 --api-key、TRENDSAGI_API_KEY，然后是已保存的登录信息。删除内容或更改实时广告的命令会先询问确认；在脚本中请传入 --yes。退出代码：0 表示成功，1 表示 API 错误，2 表示用法无效，4 表示缺少密钥或密钥被拒绝。

命令只在 src/trendsagi/cli_spec.json 中声明一次；同一 CLI 的无依赖 Node.js 构建版本位于 npm/，并以 trendsagi on npm 的形式发布。使用指南：trendsagi.com/api-docs/integrations/cli。

客户端也可以调用任意端点：client.request("GET", "/api/integrations/delivery/health", params={"lookback_hours": 24})。

在 AI 助手中使用 TrendsAGI（无需安装）

添加托管的 MCP 服务，登录 TrendsAGI 并批准连接：

助手	设置
Claude	在 Claude 目录中打开 TrendsAGI，或前往 Settings > Connectors > Add custom connector，使用下方的 URL
Claude Code	claude mcp add --transport http trendsagi https://api.trendsagi.com/mcp，或先运行 /plugin marketplace add TrendsAGI/TrendsAGI，再运行 /plugin install trendsagi@trendsagi
ChatGPT	添加自定义连接器，并使用下方的 URL
Grok	安装 TrendsAGI 插件，或将该 URL 添加为远程 MCP 服务
Cursor	{ "mcpServers": { "trendsagi": { "url": "https://api.trendsagi.com/mcp" } } }
Gemini CLI	gemini extensions install https://github.com/TrendsAGI/TrendsAGI

https://api.trendsagi.com/mcp

然后询问 “本周科技领域增长最快的趋势是什么？我应该向谁推广？” 托管工具为只读，每次调用计为 1 次 API 请求。每个连接都有单独的密钥，列在 Profile > API Keys 下，名称为“AI connector: ”；删除该密钥即可断开连接。不支持 OAuth 的客户端可以通过 Authorization: Bearer <key> 发送 API 密钥。指南：trendsagi.com/mcp。

在浏览器的 Agent 中使用 TrendsAGI（WebMCP）

WebMCP 允许网页将工具提供给浏览器内置的 AI Agent（Chrome 和 Edge 目前处于源试验阶段，此外还有 ChatGPT 桌面应用和 Brave Leo）。登录 app.trendsagi.com 后，该应用会通过 document.modelContext 注册 TrendsAGI 的只读工具，因此 Agent 会使用你的会话调用这些工具：无需连接器或 API 密钥，调用计为应用使用，而非 API 用量。trendsagi.com 向所有访客提供公开工具（文档搜索、趋势报告、套餐和免费计算器）。

若要在自己的网站上提供 TrendsAGI 工具，请在页面中注册这些工具，并在自己的服务上运行它们，以保管 API 密钥：

tools = TrendsAGITools(TrendsAGIClient(api_key=os.environ["TRENDSAGI_API_KEY"]))

tools.webmcp()                     # serve to your page: name, description, inputSchema, annotations
tools.call("list_trends", args)    # run the call your page forwards

webmcp/ 中包含浏览器模块和 FastAPI 服务。指南：trendsagi.com/webmcp。

Agent 工具

一个注册表，支持所有格式。工具默认为只读；只有设置 allow_writes=True（或使用 trendsagi mcp --allow-writes）时，才会显示 add_to_watchlist 和 update_recommendation。

工具	Agent 可获取的内容
list_trends	按类别或短语查看热门趋势，并按速度、增长或数量排序
list_trend_categories	有效的类别名称
search_trend_insights	与主题匹配的趋势和洞察
get_trend / get_trend_analytics	单个趋势及其数量时间序列
get_trend_ai_insights	摘要、关键主题、情绪、受众和营销角度
list_recommendations	有证据支持的行动建议及决策简报
list_crisis_events	受监测主题的声誉和危机事件
list_watchlist / get_api_usage	已关注的主题和每日剩余配额
read_data_schema / execute_sql	只读 SQL，适用于需要筛选、联接或聚合的问题
find_capability	查询 TrendsAGI 是否能完成某项任务，以及应使用哪个工具或应用页面

OpenAI

import json, os
from openai import OpenAI
from trendsagi import TrendsAGIClient, TrendsAGITools

tools = TrendsAGITools(TrendsAGIClient(api_key=os.environ["TRENDSAGI_API_KEY"]))
openai = OpenAI()
messages = [{"role": "user", "content": "Find a fast-rising Technology trend and suggest a campaign angle."}]

while True:
    reply = openai.chat.completions.create(model="gpt-5-mini", messages=messages, tools=tools.openai())
    message = reply.choices[0].message
    messages.append(message)
    if not message.tool_calls:
        print(message.content)
        break
    for call in message.tool_calls:
        result = tools.call(call.function.name, call.function.arguments)
        messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(result)})

Claude、LangChain 等

tools.anthropic()         # Anthropic Messages API tools=
tools.openai_responses()  # OpenAI Responses API tools=
tools.langchain()         # LangChain StructuredTools (pip install "trendsagi[langchain]")
tools.webmcp()            # WebMCP descriptors for document.modelContext.registerTool

使用 Claude 时，传入 tools=tools.anthropic()，并用 {"type": "tool_result", "tool_use_id": block.id, "content": json.dumps(tools.call(block.name, block.input))} 响应每个 tool_use 块。tools.call 永不抛出异常：错误会以 {"error": ...} 的形式返回，因此模型可以读取速率限制或无效参数等错误并进行处理。

本地 MCP 服务

pip install "trendsagi[mcp]"
claude mcp add trendsagi --env TRENDSAGI_API_KEY=your_api_key -- trendsagi mcp

或者，在任何 MCP 客户端的 JSON 配置中使用（Claude Desktop、Cursor、VS Code）：

{ "mcpServers": { "trendsagi": { "command": "trendsagi-mcp", "env": { "TRENDSAGI_API_KEY": "your_api_key" } } } }

使用 SQL 查询

对于没有单个端点可返回答案的问题，例如按类别统计增长情况或符合监控列表的趋势：

schema = client.get_data_schema()   # tables, columns, rules, examples
result = client.execute_sql(
    """
    SELECT category, count(*) AS trends, round(avg(growth_pct)::numeric, 1) AS avg_growth_pct
    FROM trends
    WHERE last_seen_at > now() - interval '7 days' AND growth_pct IS NOT NULL
    GROUP BY category ORDER BY avg_growth_pct DESC
    """,
    max_rows=20,
)
print(result["columns"], result["rows"])

表：trends、trend_snapshots（90 天的读数）、trend_categories、trend_insights、watchlist、recommendations 和 crisis_events；最后三张表仅包含你自己账户的行。查询必须是经过验证的单条 SELECT 语句，以只读方式运行，最长 5 秒，并计为 1 次 API 请求。查询遭拒时会引发 exceptions.QueryError，其中包含 code（例如 unknown_table 或 timeout），并在已知时包含 hint 和 position。

附带决策简报的建议

recommendations = client.get_recommendations(match_user_interests=True, priority="high", sort="priority", limit=10)
for rec in recommendations.recommendations:
    brief = rec.decision_brief
    if brief and brief.actionable:
        print(rec.title, brief.why_now, brief.next_steps[:1])

每份简报都会说明采取行动的时机为何恰当、背后的测量信号以及具体的后续步骤。置信度分数衡量的是证据的完整性，而非成功的概率；当信号已过时或不完整时，可使用 actionable 和 data_quality 暂缓行动。

在你自己的基础设施中执行广告

GoogleAdsExecutor、MetaAdsExecutor、TikTokAdsExecutor 和 LinkedInAdsExecutor 在运行时接收凭据，使用确定性的幂等键，并支持试运行预览和严格验证：

from trendsagi.integrations import GoogleAdsExecutor

insight = client.get_ai_insights(trend_id)  # the trend you decided to act on
google = GoogleAdsExecutor({
    "access_token": os.environ["GOOGLE_ADS_ACCESS_TOKEN"],
    "developer_token": os.environ["GOOGLE_ADS_DEVELOPER_TOKEN"],
})
preview = google.apply_targeting(insight, customer_id="1234567890", campaign_id="9876543210", dry_run=True, strict_mode=True)
print(preview.response)  # inspect before any real change

所有执行器的详情请参阅 INTEGRATIONS_BYOC.md。

错误

from trendsagi import exceptions

try:
    client.get_trends(limit=5)
except exceptions.RateLimitError:
    ...  # back off and retry
except exceptions.AuthenticationError:
    ...  # invalid or revoked key

其他命令

trendsagi mcp [--allow-writes]                              # MCP server over stdio
trendsagi scaffold --type docker --output-dir ./runner      # executor runner template
trendsagi scaffold --type terraform --output-dir ./infra    # infrastructure template

套餐与限制

免费 Developer 套餐包含 1 个 API 密钥，每天可调用 API 100 次；Advantage、Scale 和 Enterprise 套餐提高每日限额，并增加密钥和团队功能。超出每日限额的调用将按超额用量计费。请参阅定价。

链接

• API 文档和端点参考
• CLI 指南
• MCP 服务指南和 WebMCP 指南
• 更新日志
• 支持：trendsagi.com/contact 或联系 [email protected]

许可证

MIT。请参阅 LICENSE。