SuperAPI AI 工具集

joule-a2a-agent

智能体与模型

查看项目

更新于 11-03 16:15

技能介绍

本技能用于生成一个完整的 pro-code AI 智能体项目:使用 LangGraph(配合 @a2a-js/sdk 0.3.10 或 a2a-sdk)实现支持 A2A 协议 v0.3.0 的智能体,以 SAP GenAI Hub(OrchestrationClient)作为大模型提供方;把智能体作为 REST API 部署到 SAP BTP Cloud Foundry(cf push 或 MTA);再用多文件 DTA 格式创建带 A2A 动作的 Joule 能力,并通过 CLI 编译并部署该能力到 Joule。

工作原理:智能体在 Cloud Foundry 上以 TypeScript 或 Python Web 服务运行并暴露 A2A 端点;Joule 通过 /.well-known/agent.json 的 Agent Card 发现它;用户提示匹配能力时,Joule 发送 A2A 任务,智能体用 LangGraph 处理并通过 SAP GenAI Hub 推理,结果回传至 Joule 聊天界面。Joule 与智能体的连接使用 BTP Destination 加定义 agent-request 动作类型的 Joule 能力 YAML。

前置条件:Joule DTA schema 需 3.28.0 及以上,capability.sapdas.yaml 须写 schema_version: "3.28.0",旧版本租户编译成功但部署会报 schema 版本过高错误;可用 joule login、joule status 检查。其他条件包括:启用 Cloud Foundry 的 BTP 子账户、部署了 GenAI Hub 模型的 AI Core 实例、安装 Joule CLI(npm install -g @sap/joule-studio-cli)、CF CLI 已登录、Joule CLI 已登录、配置 Joule App2App IAS 流程并分配角色、BTP 角色 extensibility_developer 与 capabilityadmin;CAP 智能体另需 mbt(npm install -g mbt)与 MTA CF CLI 插件(cf install-plugin multiapps)。需以插件方式启动 Claude Code:claude --plugin-dir <path-to-sap-a2a-agent-toolkit>。

使用流程:第一步收集需求(语言:TypeScript 默认或 Python;框架:Express 默认或 CAP,CAP 仅支持 TypeScript;智能体名称与用途;工具/API;GenAI Hub 模型,默认 gpt-4.1;BTP landscape 详情,未知可先用占位值)。第二步用 scaffold 脚本生成项目,三种配置分别对应 TypeScript + Express(src/index.ts、agent.ts、executor.ts、agentCard.ts、tools.ts、llm.ts 及 joule-capability 目录)、TypeScript + CAP(srv/server.ts、agent-executor.ts、service.cds、tools/、utils/ 及 mta.yaml)、Python + Express(Starlette + A2AStarletteApplication,langchain-openai ChatOpenAI 直连 AI Core 端点,不使用 generative-ai-hub-sdk 以避免 pydantic 版本冲突)。三种配置在服务端、A2A SDK、LLM 接入、部署方式、鉴权、智能体模式、中断支持和 buildpack 上各有差异,但 Joule 能力 YAML 文件完全一致。第三步按需求定制工具、系统提示、Agent Card 与 capability.sapdas.yaml 中的场景描述。第四步部署到 Cloud Foundry 并用 curl 验证 agent.json;第五步创建 BTP Destination(名称须与 system_aliases 中的 destination 一致,鉴权用 NoAuthentication 或 OAuth2ClientCredentials);第六步安装 Joule CLI 并执行 joule deploy ./da.sapdas.yaml --compile -n "<assistant_name>";第七步在 Joule 中用匹配场景描述的提示测试,失败时检查 destination、agent card 可访问性、场景描述匹配及 cf logs。修改已有智能体时,新增工具需注册并补充 agent card 技能后重新部署;换模型改 MODEL_NAME 环境变量;更新能力需重新编译部署;扩容调整 manifest.yml 或 mta.yaml 中实例与内存。

注意事项:A2A 协议 v0.3.0 使用 HTTP(S) 上的 JSON-RPC 2.0,须处理 message/send,可选 message/stream;Agent Card 必须位于 /.well-known/agent.json;metadata.namespace 必须为 joule.ext,否则部署报命名空间校验错误;da.sapdas.yaml 使用 schema 1.4.0,capability.sapdas.yaml 使用 3.28.0;TypeScript 使用 @sap-ai-sdk/langchain 的 OrchestrationClient(自动读取 VCAP_SERVICES)。

适用场景:需要在 SAP BTP 上构建并部署与 Joule 集成的 A2A 智能体、并配置 Destination 与能力发布的开发场景。限制:依赖特定 schema 版本与 BTP 角色权限,CAP 仅支持 TypeScript,Python 仅支持 Express(Starlette);其他细节资料暂未提供。