AgentScope Agent Service 怎么接入钉钉渠道？

AgentScope Agent Service 怎么接入钉钉渠道？

【免费下载链接】agentscopeBuild and run agents you can see, understand and trust.项目地址: https://gitcode.com/GitHub_Trending/ag/agentscope

要把 AgentScope 2.0 的 Agent Service 接到钉钉里，让钉钉用户通过单聊或群聊 @机器人 直接和 Agent 对话，你需要完成三件事：装好带渠道依赖的 AgentScope、在服务端把DingTalkChannel注册进create_app、再在 Web UI（或调用/channels接口）里创建一条钉钉渠道并填上钉钉应用的 Client ID / Client Secret。本文按这条主路径给出可执行的步骤，适用环境为examples/agent_service示例所要求的前提：Python ≥ 3.11、Redis 作为后端存储、Node.js ≥ 20（仅 Web UI 需要）。

准备：安装依赖并确认渠道已注册

钉钉渠道依赖官方的dingtalk-streamSDK（版本要求>=0.24.3，见 pyproject.toml 中channelextra），而fullextra 已经包含了它：

uv pip install agentscope[full]

同时按 examples/agent_service/README.md 的 Quickstart 安装并启动 Redis（macOS、Linux、Docker 三种方式文档都给了），例如：

# Linux (systemd) sudo apt install redis-server sudo systemctl start redis-server # Docker (cross-platform) docker run --rm -p 6379:6379 redis:7

然后检查 examples/agent_service/main.py：示例默认就把三个渠道类型注册进了应用，DingTalk 已在其中，无需改动：

channels=[ DingTalkChannel, DiscordChannel, FeishuChannel, ],

启动服务：

cd examples/agent_service python main.py

服务默认监听0.0.0.0:8000。钉钉渠道走官方 Stream SDK 的长连接（见 src/agentscope/app/channel/_dingtalk/_channel.py 顶部说明），不需要为它配置公网回调地址；出站消息、媒体、卡片则全部通过钉钉 OpenAPI 发送。

创建钉钉渠道

主路径：通过 Web UI 创建

在另一个终端启动示例配套的 Web UI：

cd examples/web_ui/ pnpm install pnpm dev

在 Web UI 里把 API endpoint 设置为http://localhost:8000，进入渠道管理页创建渠道，按表单依次完成（表单校验规则来自 channel-form.tsx 的isChannelFormValid，缺项不能提交）：

1. 渠道类型选DingTalk。
2. 填写渠道名称（必填）。
3. 凭据：Client ID和Client Secret，即钉钉应用的 AppKey 和 AppSecret（字段定义见 src/agentscope/app/channel/_dingtalk/_channel.py 中的Credentials模型）。表单字段是由GET /channels/types返回的credentials_schema动态渲染的，选中钉钉类型后这两个输入框会自动出现。
4. 选择一个聊天模型（chat_model_config，必填，模型来自服务里已配置好的凭据）。
5. 路由绑定（Routing）：示例 UI 的默认绑定是match_key: "chat_id"、match_value: "*"、session_scope: "per_chat"，并把消息路由到你指定的agent_id。match_value可填GET /channels/{id}/chat_ids返回的具体会话 id 来限定只接某些会话，*表示全部。
6. 提交后渠道以启用状态创建（enabled: true）。

备选路径：直接调用 HTTP 接口

渠道的完整 API 见 src/agentscope/app/_router/_channel.py：

POST /channels/ 创建渠道 GET /channels/ 列出当前用户的渠道 PATCH /channels/{id} 更新路由/会话/配置 GET /channels/{id}/status 聚合的实时连接状态 GET /channels/{id}/chat_ids 已知会话（用于路由配置） POST /channels/{id}/enable / disable

创建请求体对应 CreateChannelRequest：

{ "channel_type": "dingtalk", "name": "my-dingtalk", "credentials": { "client_id": "<你的钉钉应用 Client ID (AppKey)>", "client_secret": "<你的钉钉应用 Client Secret (AppSecret)>" }, "platform_config": { "only_at_reply": true }, "routing": { "bindings": [ { "match_key": "chat_id", "match_value": "*", "agent_id": "<服务中的 Agent ID>", "session_scope": "per_chat" } ] }, "session": { "chat_model_config": "<填服务中已配置的模型>", "permission_mode": "default" }, "enabled": true }

其中尖括号内容是读者必须替换的值：agent_id用你服务里已创建的 Agent；session.chat_model_config的具体结构以GET /channels/{id}返回的记录中的session字段为准（创建渠道时响应里会原样带回）。凭据也可以走POST /channels/bindings的绑定流程再创建，凭据不必经过浏览器表单。

钉钉平台侧配置项（platform_config）

以下选项来自 DingTalkChannel.Config，在 Web UI 的渠道表单里按 schema 动态渲染，也可通过PATCH /channels/{id}的platform_config更新：

配置项	默认值	作用
only_at_reply	true	群聊中仅在机器人被 @ 时才回复
show_tool_process	false	在回复中内联展示工具调用和结果
show_thinking	false	在回复中内联展示模型推理过程
max_media_bytes	10 * 1024 * 1024	单个收发附件的大小上限
streaming_card_template_id	官方公开的 AI 卡片模板	流式回复用的 AI 卡片模板；清空后改为普通 Markdown 消息回复
approval_card_template_id	公开审批卡片模板	工具审批卡片模板；清空后需要审批的工具调用会卡住，渠道会发一条提示文案说明

验证接入结果

1. 连接状态：调用GET /channels/{id}/status（Web UI 的渠道详情页也展示）。渠道源码里的状态机是：先connecting，Stream 客户端建立 websocket 后变为connected；断开后如果曾连上过则进入retrying（SDK 自带重连）；发生异常时为failed并带last_error字段，日志里会记录DingTalk '<channel_id>' Stream client failed。看到connected说明 Stream 长连接已建立。
2. 收到消息：在钉钉里私聊机器人，或在群里 @机器人 发一条消息。only_at_reply保持默认true时，群里未被 @ 的消息会被直接忽略，这是预期行为而非故障。
3. 回复形式：默认配置下回复以流式 AI 卡片呈现；如果卡片创建或更新失败，渠道会回退成一条或多条 Markdown 消息（超过 4000 字会拆分，max_message_length为 4000）。
4. 会话列表：GET /channels/{id}/chat_ids返回已知会话。注意钉钉的限制：平台侧没有暴露应用机器人的会话枚举 API，所以该列表只包含本进程实际收到过消息回调的会话（源码中list_bot_chats的 docstring 明确说明）。想扩大路由范围前，先让目标会话里发过一条消息。

边界与限制

• 出站文件类型：除图片外，钉钉侧只接受doc、docx、pdf、rar、xlsx、zip后缀的文件（见 src/agentscope/app/channel/_dingtalk/_openapi.py 的_SUPPORTED_FILE_TYPES），其他后缀会被渠道拒绝并记 warning。
• 工具审批：如果 Agent 启用了需要人工确认的工具调用，钉钉侧会以审批卡片呈现；approval_card_template_id被清空时无法投递卡片，聊天中会出现「无法展示工具审批卡片」的提示文案，运行会停在等待审批状态。
• 凭据不可事后修改：PATCH /channels/{id}不支持改渠道类型和凭据（UpdateChannelRequest 注释标明 type/credentials immutable），填错 AppKey/AppSecret 只能删除渠道重建。
• 服务重启后，之前记录的已知会话仍在（走 Redis 存储），但chat_ids中「被动观察到」的部分要等新回调进来才会出现。

接入完成后的自然延伸：通过 Web UI 的渠道详情页调整路由绑定和platform_config，或参考 README 中 "What Next" 一节继续定制main.py（MCP、中间件、workspace manager）。

【免费下载链接】agentscopeBuild and run agents you can see, understand and trust.项目地址: https://gitcode.com/GitHub_Trending/ag/agentscope