用 Scalar Agent SDK 构建 Jira 到 Discord 的自动事件监控 Agent【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar导读本文基于 Scalar 开源仓库中 incident-monitor.md 这份实战手册完整演示如何用 Scalar 的 Agent SDKscalar/agent/scalar-agent构建一个后台事件监控 Agent定时轮询 Jira 中新增的高优先级工单自动把格式化告警推送到 Discord 频道彻底告别手动复制工单信息到聊天窗口的重复劳动。读完本文你将掌握 Scalar MCP 安装Installation的配置方法、TypeScriptVercel AI SDK与 PythonOpenAI Agents SDK两套完整实现以及 crontab 与 GitHub Actions 两种定时调度方案。场景与工作原理这个 Cookbook 的核心是一个后台 Agent它不面向交互式对话而是按固定节奏每 15 分钟执行一次监控任务。运行链路可以概括为通过 Scalar 的Installation MCPhttps://mcp.scalar.com/mcp/YOUR_INSTALL_ID见 mcp.md把 Jira 的搜索接口与 Discord 的发消息接口暴露给 AgentAgent 用 Jira API 查询最近 15 分钟内创建、优先级为 High 或 Critical 的工单若发现新工单逐条调用 Discord API 按固定格式发送告警若没有新工单则什么都不做。你可以把它放在 cron 上每 15 分钟执行一次也可以由 Jira 的 webhook 触发——这是两种完全不同的驱动方式定时轮询pull适合低成本持续监控事件驱动webhook push则能即时响应读者可根据团队现状选择。Scalar 的 MCP 与 Agent 体系在 index.md 中被总结为四个关键特性Just-in-time tool calls用极少的工具覆盖任意 API操作细节按需获取而非首轮全量注入、Secure delegated auth按安装维度配置 OAuth/API key/bearer token上游凭据永不下发到 Agent、Scoped access每个 MCP 安装可精确控制能调用哪些 API 与端点、Isolated execution沙箱化执行多个 Agent 与自动化可安全共享同一目录。前置条件在动手前请确认具备以下环境与账号类别要求运行时Node.js 18TypeScript 方案或Python 3.10Python 方案Scalar个人访问令牌Account → API Keys与 Installation ID模型OpenAI API KeyJira具有 API 访问权限的 Jira 账号Discord目标频道的 Webhook URL或 bot token见下文注原文档中 Discord 使用的是bot token用于 MCP 认证而.env之外还需要你准备YOUR_CHANNEL_ID作为告警消息的目标频道 ID。项目初始化两种语言二选一即可二者使用同一个 Scalar MCP 安装因此共享同一份 Dashboard 配置。TypeScript 方案mkdir incident-monitor cd incident-monitor npm init -y npm install scalar/agent ai ai-sdk/openai dotenv tsxscalar/agentScalar 官方 TypeScript SDK提供agentScalar客户端aiVercel AI SDK 核心generateText、stepCountIsai-sdk/openaiOpenAI 模型接入dotenv读取.envtsx直接运行 TypeScript 文件。Python 方案Python 侧使用 OpenAI Agents SDK配合 sdk.md 中介绍的scalar-agent包mkdir incident-monitor cd incident-monitor python3 -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install scalar-agent[openai] python-dotenvscalar-agent[openai]Scalar 官方 Python SDK 及 OpenAI Agents SDK 依赖python-dotenv加载.env文件。配置环境变量在项目根目录创建.env文件SCALAR_TOKENyour-scalar-personal-token SCALAR_INSTALLATION_IDyour-installation-id OPENAI_API_KEYyour-openai-api-key安全提醒.env包含真实凭据务必将其加入.gitignore切勿提交到版本库。在 CI 中请改用 GitHub Actions Secrets下文有完整示例。在 Scalar Dashboard 中配置 MCP 工具登录 dashboard.scalar.com按照 mcp.md 的安装流程完成三步添加 Jira 工具进入MCP → Add tool → Jira在Authentication中粘贴你的 Jira API Token 并保存然后为GET /rest/api/3/search启用Execute模式。添加 Discord 工具点击 Add tool → Discord粘贴 Discord Bot Token 并保存为POST /channels/{channel.id}/messages启用Execute模式。复制 Installation ID在 SDK 标签页复制你的 Installation ID填入.env。这里涉及 mcp.md 中定义的两个关键概念理解它们才能确保配置正确工具模式Search / Execute。每个工具对应 OpenAPI 文档中的一个 operation。Search模式只暴露端点供查找不会向你的 API 发起真实请求Execute模式才会发起真实的、携带认证的请求。本文要求对 Jira 搜索接口和 Discord 发消息接口都启用Execute——这是 Agent 真正动手的前提。下图展示了在 Dashboard 中配置工具端点开关的界面认证模式Global / Passthrough。认证按 Installation 维度配置让 MCP Server 能代表你调用 API同时不把上游凭据暴露给客户端。Global模式在安装上存储一份凭据OAuth、API key 或 bearer token每次调用统一使用Passthrough模式则由调用方在请求头或查询参数中携带凭据Scalar 逐请求转发且不落盘存储。本文中 Jira 与 Discord 均属于整个团队共用一个上游账号的场景直接采用 Global 模式即可。认证配置界面如下此外Installation MCP 默认是私有的团队成员凭 Personal Access Token 连接外部人员则需要你授予 OAuth 访问权限详见 authentication/index.md。你在 Dashboard 里配置的每一步选择暴露哪些端点、存储哪种认证都决定了这个私有端点的行为边界。初始化 Scalar 客户端TypeScriptimport dotenv/config import { agentScalar } from scalar/agent import { generateText, stepCountIs } from ai import { openai } from ai-sdk/openai const scalar agentScalar({ token: process.env.SCALAR_TOKEN }) const model openai(gpt-4o)Pythonimport os from dotenv import load_dotenv from scalar_agent import agent_scalar load_dotenv() scalar agent_scalar(tokenos.environ[SCALAR_TOKEN])根据 sdk.mdSDK 的初始化参数如下两种语言等价参数类型说明token/tokenstring/strScalar 个人令牌用于向你的 MCP 服务器发起请求时认证baseUrl/base_urlstring/strScalar MCP 服务器的 Base URL默认指向 Scalar 官方环境初始化后通过scalar.installation(installationId)拿到 Installation 引用它是后续一切工具绑定tool binding的入口——TypeScript 侧生成 Vercel AI SDK 工具集Python 侧生成 OpenAI Agents SDK 的 MCP 服务器参数二者指向同一个 Dashboard 安装。监控逻辑核心实现Agent 的行为逻辑一句话概括只在有东西需要报告时才行动。它查询 Jira 中创建于过去 15 分钟、优先级为 High 或 Critical 的工单逐条向 Discord 发送摘要没有新工单则静默结束。TypeScript 实现async function monitor() { const installation await scalar.installation(process.env.SCALAR_INSTALLATION_ID) const tools await installation.createVercelAITools() const fifteenMinutesAgo new Date(Date.now() - 15 * 60 * 1000).toISOString() const { text } await generateText({ model, tools, stopWhen: stepCountIs(10), system: You are an incident monitor with access to Jira and Discord. Search Jira for new high-priority issues. Post alerts to Discord. Current time: ${new Date().toISOString()}, prompt: Check for new incidents: 1. Search Jira for issues created after ${fifteenMinutesAgo} with priority High or Critical. 2. If any are found, post one message per issue to Discord channel ID YOUR_CHANNEL_ID in this format: [PRIORITY] — [ISSUE KEY]: [SUMMARY] Assignee: [assignee or Unassigned] Project: [project name] Link: [issue URL] 3. If no issues are found, do nothing., }) console.log(text) } monitor()Python 实现import asyncio import os from datetime import datetime, timedelta, timezone from agents import Agent, Runner from agents.mcp import MCPServerStreamableHttp async def monitor() - None: installation scalar.installation(os.environ[SCALAR_INSTALLATION_ID]) server MCPServerStreamableHttp(**installation.create_openai_mcp()) await server.connect() fifteen_minutes_ago (datetime.now(timezone.utc) - timedelta(minutes15)).isoformat() now datetime.now(timezone.utc).isoformat() agent Agent( nameincident-monitor, instructions( You are an incident monitor with access to Jira and Discord.\n Search Jira for new high-priority issues. Post alerts to Discord.\n fCurrent time: {now} ), mcp_servers[server], ) result await Runner.run( agent, fCheck for new incidents: 1. Search Jira for issues created after {fifteen_minutes_ago} with priority High or Critical. 2. If any are found, post one message per issue to Discord channel ID YOUR_CHANNEL_ID in this format: [PRIORITY] — [ISSUE KEY]: [SUMMARY] Assignee: [assignee or Unassigned] Project: [project name] Link: [issue URL] 3. If no issues are found, do nothing., max_turns10, ) print(result.final_output) await server.cleanup() asyncio.run(monitor())两个实现的关键差异维度TypeScriptPython工具绑定installation.createVercelAITools()返回工具集直接传给generateTextinstallation.create_openai_mcp()生成参数构造MCPServerStreamableHttp步骤上限stopWhen: stepCountIs(10)max_turns10时间窗口new Date(Date.now() - 15 * 60 * 1000).toISOString()datetime.now(timezone.utc) - timedelta(minutes15)生命周期无显式清理await server.connect()/await server.cleanup()成对出现值得注意的实现细节stopWhen: stepCountIs(10)与max_turns10都用于限制 Agent 的推理步数上限防止它在意外情况下无限循环调用工具——这是后台无人值守脚本的必备护栏。时间窗口必须传绝对时间。prompt 中注入的是fifteenMinutesAgo的 ISO 时间戳同时把now注入 system/instructions而不是15 分钟前这种相对描述避免模型基于自身不准确的时间感计算查询边界。getOpenAPI等底层工具调用是按需展开的。Scalar 的 MCP 只给模型极少的元工具具体的 operation 细节在模型决定调用某个端点时才拉取见 index.md 的 Just-in-time tool calls 特性因此多 API 组合也不会撑爆上下文窗口。完整脚本将上面两个版本分别保存为monitor.ts与monitor.pyTypeScript 文件需补全dotenv/config导入Python 文件在main()中初始化scalar并在__main__入口执行。TypeScriptmonitor.tsimport dotenv/config import { agentScalar } from scalar/agent import { generateText, stepCountIs } from ai import { openai } from ai-sdk/openai const scalar agentScalar({ token: process.env.SCALAR_TOKEN }) const model openai(gpt-4o) async function monitor() { const installation await scalar.installation(process.env.SCALAR_INSTALLATION_ID) const tools await installation.createVercelAITools() const fifteenMinutesAgo new Date(Date.now() - 15 * 60 * 1000).toISOString() const { text } await generateText({ model, tools, stopWhen: stepCountIs(10), system: You are an incident monitor with access to Jira and Discord. Search Jira for new high-priority issues. Post alerts to Discord. Current time: ${new Date().toISOString()}, prompt: Check for new incidents: 1. Search Jira for issues created after ${fifteenMinutesAgo} with priority High or Critical. 2. If any are found, post one message per issue to Discord channel ID YOUR_CHANNEL_ID in this format: [PRIORITY] — [ISSUE KEY]: [SUMMARY] Assignee: [assignee or Unassigned] Project: [project name] Link: [issue URL] 3. If no issues are found, do nothing., }) console.log(text) } monitor()Pythonmonitor.pyimport asyncio import os from datetime import datetime, timedelta, timezone from agents import Agent, Runner from agents.mcp import MCPServerStreamableHttp from dotenv import load_dotenv from scalar_agent import agent_scalar load_dotenv() async def main() - None: scalar agent_scalar(tokenos.environ[SCALAR_TOKEN]) installation scalar.installation(os.environ[SCALAR_INSTALLATION_ID]) server MCPServerStreamableHttp(**installation.create_openai_mcp()) await server.connect() fifteen_minutes_ago (datetime.now(timezone.utc) - timedelta(minutes15)).isoformat() now datetime.now(timezone.utc).isoformat() agent Agent( nameincident-monitor, instructions( You are an incident monitor with access to Jira and Discord.\n Search Jira for new high-priority issues. Post alerts to Discord.\n fCurrent time: {now} ), mcp_servers[server], ) result await Runner.run( agent, fCheck for new incidents: 1. Search Jira for issues created after {fifteen_minutes_ago} with priority High or Critical. 2. If any are found, post one message per issue to Discord channel ID YOUR_CHANNEL_ID in this format: [PRIORITY] — [ISSUE KEY]: [SUMMARY] Assignee: [assignee or Unassigned] Project: [project name] Link: [issue URL] 3. If no issues are found, do nothing., max_turns10, ) print(result.final_output) await server.cleanup() if __name__ __main__: asyncio.run(main())运行与验证npx tsx monitor.ts # 或 python monitor.py运行前请把 prompt 中的YOUR_CHANNEL_ID替换为真实的 Discord 频道 ID告警将发往该频道。一次成功的运行输出大致如下Found 2 new high-priority issues in Jira: Posted to #incidents: Critical — OPS-1842: API timeout on large payload uploads Assignee: Sarah Chen Project: Platform Operations Link: https://yourorg.atlassian.net/browse/OPS-1842 High — OPS-1843: Dashboard failing to load for EU region Assignee: Unassigned Project: Platform Operations Link: https://yourorg.atlassian.net/browse/OPS-1843注意输出中的Found 2 new ... / Posted to #incidents这类汇总文本来自模型对执行结果的归纳——模型在完成工具调用后会总结发现与已执行的投递动作。告警正文严格遵循 prompt 中约定的格式优先级、工单号、摘要、经办人、项目、链接让值班人员一眼即可定位问题。定时调度后台监控的实用价值取决于自动二字原文档给出了两种零成本调度方案。crontab每 15 分钟crontab -e*/15 * * * * cd /path/to/incident-monitor npx tsx monitor.ts monitor.log 21 # Python: */15 * * * * cd /path/to/incident-monitor .venv/bin/python monitor.py monitor.log 21*/15 * * * *是标准的每 15 分钟触发表达式。cd到项目目录是为了确保相对路径.env能被正确加载 monitor.log 21将标准输出与错误统一追加到日志文件便于事后排查。Python 方案务必使用虚拟环境内的解释器.venv/bin/python避免依赖冲突。GitHub ActionsTypeScript 工作流.github/workflows/incident-monitor.ymlname: Incident Monitor on: schedule: - cron: */15 * * * * # every 15 minutes workflow_dispatch: jobs: monitor: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 22 - run: npm install - run: npx tsx monitor.ts env: SCALAR_TOKEN: ${{ secrets.SCALAR_TOKEN }} SCALAR_INSTALLATION_ID: ${{ secrets.SCALAR_INSTALLATION_ID }} OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}Python 工作流.github/workflows/incident-monitor-python.ymlname: Incident Monitor (Python) on: schedule: - cron: */15 * * * * workflow_dispatch: jobs: monitor: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-pythonv5 with: python-version: 3.12 - run: pip install scalar-agent[openai] python-dotenv - run: python monitor.py env: SCALAR_TOKEN: ${{ secrets.SCALAR_TOKEN }} SCALAR_INSTALLATION_ID: ${{ secrets.SCALAR_INSTALLATION_ID }} OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}两个工作流的共同要点workflow_dispatch:允许你在 UI 上手动触发一次运行方便上线前验证三个敏感变量全部通过${{ secrets.* }}注入绝不写死在 YAML 中——需在仓库 Settings → Secrets 中预先配置SCALAR_TOKEN、SCALAR_INSTALLATION_ID、OPENAI_API_KEY三个 Secretcron 调度在 GitHub 上是最小 5 分钟粒度*/15完全满足本文场景。一点运维提醒GitHub Actions 的schedule事件不保证在精确的整点触发高负载时会延迟若需要秒级或严格准时的监控节奏自建 cron 或 webhook 触发更合适。深入SDK 背后的 Provider 集成如果你不满足于能用可以顺着 sdk.md 了解这套 SDK 的边界与可复用性。scalar/agentTypeScript原生支持三种 Agent 运行时Vercel AI SDK基于ai-sdk/mcpcreateVercelAITools()返回可直接用于generateText/streamText的工具集——本文采用的就是这一路径OpenAI Agents SDKcreateOpenAIMCP()返回MCPServerStreamableHttp的构造参数Agent 运行时负责工具发现与执行Anthropic Claude Agent SDKcreateAnthropicMCP()返回 MCP 服务器配置配合allowedTools: [mcp__scalar__*]使用。Python 的scalar-agent同样覆盖 OpenAI Agents SDKcreate_openai_mcp()本文所用与 Claude Agent SDKcreate_anthropic_mcp()。这意味着你完全可以把本文monitor.ts/monitor.py中的初始化与工具绑定段平移到其他运行时——MCP 安装、端点暴露与认证配置全部复用无需重做。更进一步事件监控的常见增强原文档给出了三个低成本扩展方向你也可以结合团队现状自由组合接入 Resend对 Critical 优先级的工单额外直接邮件通知当班工程师形成频道告警 个人邮件的双通道按项目过滤把 Jira 搜索范围限定到特定 project key只对真正关心的业务域告警减少噪音解决状态回执增加第二遍扫描检测已转入 Done 的工单向 Discord 发送一条已解决回执形成完整的事件闭环。此外还可考虑把告警消息中的工单链接替换为 Jira 深链接、为 Critical 工单附加here或on-call提及、将运行日志接入集中式日志平台等。整套监控 Agent 的骨架——agentScalar初始化 installation工具绑定 带步骤上限的生成调用——在这些变体中保持不变这正是 Scalar Agent SDK 作为 API 与 LLM 之间薄连接层的价值所在。相关资源Agent SDK 完整文档两种语言的安装、配置参数与三种 Provider 集成示例MCP 服务器文档Docs MCP 与 Installation MCP 的区别、工具模式、认证模式、限流与滥用防护Agent 快速上手从 OpenAPI 文档到 Agent-ready 的三步流程Agent 认证文档私有访问、团队流程与客户访问组同系列其他 Cookbookbilling-sweep.mdStripe 欠费催收、revenue-dashboard.md 等均可作为本模板的复用参考【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考