joule-a2a-agent

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Joule A2A Agent on SAP BTP Cloud Foundry

在 SAP BTP Cloud Foundry 上的 Joule A2A Agent

This skill generates a complete pro-code AI agent project that:

Implements an agent with A2A protocol v0.3.0 support using LangGraph + @a2a-js/sdk 0.3.10 and SAP GenAI Hub (OrchestrationClient) as the LLM provider
Deploys to SAP BTP Cloud Foundry as a REST API (via
```
cf push
```
or MTA)
Creates a Joule capability with an A2A action using the multi-file DTA format
Provides CLI commands to compile and deploy the capability to Joule

此 skill 会生成一个完整的 pro-code AI Agent 项目，其中：

使用 A2A 协议 v0.3.0 实现 Agent，使用 LangGraph + @a2a-js/sdk 0.3.10 和 SAP GenAI Hub（OrchestrationClient）作为 LLM 提供方
通过
```
cf push
```
或 MTA 部署到 SAP BTP Cloud Foundry，作为 REST API
使用多文件 DTA 格式创建带 A2A action 的 Joule capability
提供 CLI 命令，将 capability 编译并部署到 Joule

How This Works — The Big Picture

工作原理 — 整体架构

SAP Joule can orchestrate external agents using the A2A (Agent-to-Agent) protocol. The flow is:

Your agent runs as a TypeScript or Python web service on Cloud Foundry, exposing an A2A-compatible endpoint
Joule discovers your agent by reading its Agent Card at
```
/.well-known/agent.json
```
When a user's prompt matches your agent's capability, Joule sends an A2A task to your agent
Your agent processes the request using LangGraph (with tools, LLM reasoning via SAP GenAI Hub, etc.) and returns the result
Joule presents the result to the user in the chat

The connection between Joule and your agent uses a BTP Destination + a Joule capability YAML that defines an

agent-request

action type.

SAP Joule 可以使用 A2A（Agent-to-Agent）协议编排外部 Agent。流程如下：

你的 Agent 作为 TypeScript 或 Python Web 服务运行在 Cloud Foundry 上，暴露 A2A 兼容端点
Joule 发现你的 Agent：读取
```
/.well-known/agent.json
```
处的 Agent Card
当用户的提示与你的 Agent 能力匹配时，Joule 会向你的 Agent 发送 A2A task
你的 Agent 使用 LangGraph（通过 SAP GenAI Hub 提供工具、LLM 推理等）处理请求并返回结果
Joule 在聊天中向用户展示结果

Joule 与你的 Agent 之间的连接使用 BTP Destination + 一个定义

agent-request

action 类型的 Joule capability YAML。

Prerequisites

前提条件

Joule DTA Schema Version 3.28.0+ Required: Code-based agents (BYOA) using the

agent-request

action type are supported as of DTA schema version 3.28.0. The

capability.sapdas.yaml

must specify

schema_version: "3.28.0"

If your Joule tenant runs an older schema version, the compile will succeed but deploy will fail with: "Schema version defined in config file is greater than the current schema version of Joule".

How to check your tenant's version:

Login:
```
joule login --use-env
```
(or
```
joule login 
```
)
Check status:
```
joule status
```
Try deploying — if you get the schema error, your tenant needs an update
Contact your BTP admin to request a Joule service update

Other prerequisites:

SAP BTP subaccount with Cloud Foundry enabled
AI Core service instance with a GenAI Hub model deployed
Joule CLI installed:
```
npm install -g @sap/joule-studio-cli
```
CF CLI installed and logged in (
```
cf login
```
or
```
cf login 
```
)
Joule CLI logged in (
```
joule login
```
or
```
joule login --use-env
```
)
Joule App2App IAS flow configured for Joule Studio CLI (assign required roles)
BTP roles:
```
extensibility_developer
```
+
```
capabilityadmin
```
for Joule deployments
For CAP agents:
```
mbt
```
(MTA Build Tool):
```
npm install -g mbt
```
For CAP agents: MTA CF CLI plugin:
```
cf install-plugin multiapps
```
(required for
```
cf deploy
```
with
```
.mtar
```
files)

Before you start, make sure Claude Code is started with the toolkit plugin and you are logged in to both CLIs:

bash

undefined

需要 Joule DTA Schema 3.28.0+： 使用

agent-request

action 类型的基于代码的 Agent（BYOA）自 DTA schema 3.28.0 起受支持。

capability.sapdas.yaml

必须指定

schema_version: "3.28.0"

。

如果您的 Joule 租户运行的是较旧 schema 版本，编译会成功，但部署会失败，并提示：“配置文件中定义的 Schema 版本大于 Joule 当前的 Schema 版本”。

如何检查租户版本：

登录：
```
joule login --use-env
```
（或
```
joule login 
```
）
检查状态：
```
joule status
```
尝试部署——如果出现 schema 错误，说明您的租户需要更新
联系 BTP 管理员请求 Joule 服务更新

其他前提条件：

启用了 Cloud Foundry 的 SAP BTP 子账户
AI Core 服务实例，且已部署 GenAI Hub 模型
安装 Joule CLI：
```
npm install -g @sap/joule-studio-cli
```
安装 CF CLI 并登录（
```
cf login
```
或
```
cf login 
```
）
Joule CLI 已登录（
```
joule login
```
或
```
joule login --use-env
```
）
为 Joule Studio CLI 配置 Joule App2App IAS 流程（分配所需角色）
BTP 角色：
```
extensibility_developer
```
+
```
capabilityadmin
```
（用于 Joule 部署）
对于 CAP Agent：
```
mbt
```
（MTA 构建工具）：
```
npm install -g mbt
```
对于 CAP Agent：MTA CF CLI 插件：
```
cf install-plugin multiapps
```
（
```
cf deploy
```
部署
```
.mtar
```
文件时需要）

开始之前，请确保 Claude Code 已使用 toolkit 插件启动，并且已登录两个 CLI：

bash

undefined

Start Claude Code with the SAP A2A Agent Toolkit plugin

使用 SAP A2A Agent Toolkit 插件启动 Claude Code

claude --plugin-dir <path-to-sap-a2a-agent-toolkit>

Log in to Cloud Foundry

登录 Cloud Foundry

cf login -a https://api.cf.<landscape>.hana.ondemand.com

Log in to Joule

登录 Joule

joule login

undefined

joule login

undefined

Workflow

工作流程

When the user asks to create/modify a Joule A2A agent, follow these steps:

当用户要求创建/修改 Joule A2A Agent 时，请按以下步骤操作：

Step 1: Gather Requirements

第一步：收集需求

Ask the user:

Language — TypeScript (default) or Python?
Framework — Express (default, lightweight) or CAP (enterprise, MTA deploy)? Note: CAP is TypeScript-only.
Agent name and purpose — what should this agent do?
Tools/APIs — what external services or APIs should the agent call?
SAP GenAI Hub model — which model deployed on AI Core? (default:
```
gpt-4.1
```
)
BTP landscape details — CF API endpoint, org, space (if they know them)

If the user is unsure about BTP details, generate the project anyway with placeholder values.

询问用户：

语言 — TypeScript（默认）还是 Python？
框架 — Express（默认，轻量）还是 CAP（企业级，MTA 部署）？注意：CAP 仅支持 TypeScript。
Agent 名称和用途 — 这个 Agent 应该做什么？
工具/API — Agent 应调用哪些外部服务或 API？
SAP GenAI Hub 模型 — AI Core 上部署了哪个模型？（默认：
```
gpt-4.1
```
）
BTP landscape 详细信息 — CF API 端点、org、space（如果用户知道）

如果用户不确定 BTP 详细信息，也请使用占位值生成项目。

Step 2: Generate the Agent Project

第二步：生成 Agent 项目

The project can be generated in three configurations:

项目可以使用三种配置生成：

a) TypeScript + Express (default)

a) TypeScript + Express（默认）

Run the scaffold script:

bash

bash <skill-path>/scripts/scaffold-ts.sh \
  --name <agent-name> \
  --framework express \
  --namespace <company-namespace> \
  --output <output-dir> \
  --description "<agent description>" \
  --landscape <cf-landscape>

Or manually using

references/langgraph-a2a-agent-typescript.md

references/cf-deployment-typescript.md

<agent-name>/
├── src/
│   ├── index.ts              # Express + A2A server entry point
│   ├── agent.ts              # LangGraph.js ReAct agent
│   ├── executor.ts           # A2A protocol bridge
│   ├── agentCard.ts          # Agent Card definition
│   ├── tools.ts              # Agent's tools (Zod schemas)
│   └── llm.ts                # SAP GenAI Hub configuration
├── joule-capability/
│   ├── capability.sapdas.yaml
│   ├── capability_context.yaml
│   ├── da.sapdas.yaml
│   ├── functions/call_agent.yaml
│   └── scenarios/invoke_agent.yaml
├── package.json
├── tsconfig.json
├── manifest.yml
├── Procfile
├── .env.example
└── README.md

运行脚手架脚本：

bash

bash <skill-path>/scripts/scaffold-ts.sh \
  --name <agent-name> \
  --framework express \
  --namespace <company-namespace> \
  --output <output-dir> \
  --description "<agent description>" \
  --landscape <cf-landscape>

或者使用

references/langgraph-a2a-agent-typescript.md

references/cf-deployment-typescript.md

手动创建。

<agent-name>/
├── src/
│   ├── index.ts              # Express + A2A 服务入口
│   ├── agent.ts              # LangGraph.js ReAct Agent
│   ├── executor.ts           # A2A 协议桥接
│   ├── agentCard.ts          # Agent Card 定义
│   ├── tools.ts              # Agent 工具（Zod schemas）
│   └── llm.ts                # SAP GenAI Hub 配置
├── joule-capability/
│   ├── capability.sapdas.yaml
│   ├── capability_context.yaml
│   ├── da.sapdas.yaml
│   ├── functions/call_agent.yaml
│   └── scenarios/invoke_agent.yaml
├── package.json
├── tsconfig.json
├── manifest.yml
├── Procfile
├── .env.example
└── README.md

b) TypeScript + CAP

Run the scaffold script:

bash

bash <skill-path>/scripts/scaffold-ts.sh \
  --name <agent-name> \
  --framework cap \
  --namespace <company-namespace> \
  --output <output-dir> \
  --description "<agent description>" \
  --landscape <cf-landscape>

Or manually using

references/langgraph-a2a-agent-cap-typescript.md

references/cf-deployment-cap-typescript.md

<agent-name>/
├── srv/
│   ├── server.ts              # CAP bootstrap + A2A Express endpoints
│   ├── agent-executor.ts      # LangGraph StateGraph agent orchestrator
│   ├── service.cds            # CDS service definition
│   ├── tools/
│   │   └── tools.ts           # Agent tools (Zod schemas)
│   └── utils/
│       ├── prompts.ts         # System prompt
│       ├── a2aToLangchain.ts  # A2A → LangChain converter
│       ├── a2a-operations.ts  # A2A event helpers
│       └── helpers.ts         # URL helpers
├── joule-capability/
│   ├── capability.sapdas.yaml
│   ├── capability_context.yaml
│   ├── da.sapdas.yaml
│   ├── functions/call_agent.yaml
│   └── scenarios/invoke_agent.yaml
├── package.json
├── tsconfig.json
├── mta.yaml
├── .cdsrc.sample.json
├── .env.example
└── README.md

运行脚手架脚本：

bash

bash <skill-path>/scripts/scaffold-ts.sh \
  --name <agent-name> \
  --framework cap \
  --namespace <company-namespace> \
  --output <output-dir> \
  --description "<agent description>" \
  --landscape <cf-landscape>

或者使用

references/langgraph-a2a-agent-cap-typescript.md

references/cf-deployment-cap-typescript.md

手动创建。

<agent-name>/
├── srv/
│   ├── server.ts              # CAP 启动引导 + A2A Express 端点
│   ├── agent-executor.ts      # LangGraph StateGraph Agent 编排器
│   ├── service.cds            # CDS 服务定义
│   ├── tools/
│   │   └── tools.ts           # Agent 工具（Zod schemas）
│   └── utils/
│       ├── prompts.ts         # 系统提示词
│       ├── a2aToLangchain.ts  # A2A → LangChain 转换器
│       ├── a2a-operations.ts  # A2A 事件辅助函数
│       └── helpers.ts         # URL 辅助函数
├── joule-capability/
│   ├── capability.sapdas.yaml
│   ├── capability_context.yaml
│   ├── da.sapdas.yaml
│   ├── functions/call_agent.yaml
│   └── scenarios/invoke_agent.yaml
├── package.json
├── tsconfig.json
├── mta.yaml
├── .cdsrc.sample.json
├── .env.example
└── README.md

c) Python + Express

Run the scaffold script:

bash

python <skill-path>/scripts/scaffold.py \
  --name <agent-name> \
  --namespace <company-namespace> \
  --output <output-dir> \
  --description "<agent description>" \
  --landscape <cf-landscape>

Or manually using

references/langgraph-a2a-agent.md

references/cf-deployment.md

运行脚手架脚本：

bash

python <skill-path>/scripts/scaffold.py \
  --name <agent-name> \
  --namespace <company-namespace> \
  --output <output-dir> \
  --description "<agent description>" \
  --landscape <cf-landscape>

或者使用

references/langgraph-a2a-agent.md

references/cf-deployment.md

手动创建。

Key Differences

主要差异

Aspect	TS Express	TS CAP	Python
Server	Express + jsonRpcHandler/agentCardHandler	CAP + cds.on("bootstrap")	Starlette + A2AStarletteApplication
A2A SDK	@a2a-js/sdk 0.3.10	@a2a-js/sdk 0.3.10	a2a-sdk >=0.2.7
LLM	OrchestrationClient	OrchestrationClient	langchain-openai ChatOpenAI (direct AI Core endpoint)
Deploy	`cf push` (manifest.yml)	`mbt build && cf deploy` (mta.yaml)	`cf push` (manifest.yml)
Auth	Manual	Built-in CAP auth	Manual
Agent pattern	createReactAgent	StateGraph (manual)	create_react_agent
Interrupt support	Basic (question heuristic)	Full (LangGraph interrupt())	Structured response format
Buildpack	nodejs_buildpack	nodejs_buildpack (via MTA)	python_buildpack
Reference	`langgraph-a2a-agent-typescript.md`	`langgraph-a2a-agent-cap-typescript.md`	`langgraph-a2a-agent.md`

The Joule capability YAML files are identical regardless of language/framework.

方面	TS Express	TS CAP	Python
服务端	Express + jsonRpcHandler/agentCardHandler	CAP + cds.on("bootstrap")	Starlette + A2AStarletteApplication
A2A SDK	@a2a-js/sdk 0.3.10	@a2a-js/sdk 0.3.10	a2a-sdk >=0.2.7
LLM	OrchestrationClient	OrchestrationClient	langchain-openai ChatOpenAI（直接调用 AI Core 端点）
部署	`cf push` （manifest.yml）	`mbt build && cf deploy` （mta.yaml）	`cf push` （manifest.yml）
认证	手动	CAP 内置认证	手动
Agent 模式	createReactAgent	StateGraph（手动）	create_react_agent
中断支持	基础（问题启发式）	完整（LangGraph interrupt()）	结构化响应格式
Buildpack	nodejs_buildpack	nodejs_buildpack（通过 MTA）	python_buildpack
参考	`langgraph-a2a-agent-typescript.md`	`langgraph-a2a-agent-cap-typescript.md`	`langgraph-a2a-agent.md`

Joule capability YAML 文件在三种语言/框架下完全相同。

Step 3: Customize the Agent

第三步：定制 Agent

Based on the user's requirements:

Define tools — In TypeScript: functions created with
```
tool()
```
and Zod schemas. In Python: functions decorated with
```
@tool
```
. Map each user requirement to a tool function.
- Express TS:
```
src/tools.ts
```
- CAP TS:
```
srv/tools/tools.ts
```
- Python:
```
app/tools.py
```
Configure the agent — Set the system instruction to match the agent's purpose.
- Express TS:
```
SYSTEM_PROMPT
```
  in
```
src/agent.ts
```
- CAP TS:
```
srv/utils/prompts.ts
```
- Python:
```
SYSTEM_INSTRUCTION
```
  in
```
app/agent.py
```
Set up the Agent Card — Name, skills, and supported modes.
- Express TS:
```
src/agentCard.ts
```
- CAP TS:
```
agentCard
```
  in
```
srv/server.ts
```
- Python:
```
app/agent_card.py
```
Configure
capability.sapdas.yaml
— The scenario description in
```
scenarios/invoke_agent.yaml
```
must clearly describe when Joule should invoke this agent.

根据用户需求：

定义工具 — TypeScript 中用
```
tool()
```
和 Zod schema 创建函数。Python 中用
```
@tool
```
装饰器装饰函数。将每个用户需求映射为一个工具函数。
- Express TS：
```
src/tools.ts
```
- CAP TS：
```
srv/tools/tools.ts
```
- Python：
```
app/tools.py
```
配置 Agent — 设置系统指令以匹配 Agent 的用途。
- Express TS：
```
src/agent.ts
```
  中的
```
SYSTEM_PROMPT
```
- CAP TS：
```
srv/utils/prompts.ts
```
- Python：
```
app/agent.py
```
  中的
```
SYSTEM_INSTRUCTION
```
设置 Agent Card — 名称、技能和支持的模式。
- Express TS：
```
src/agentCard.ts
```
- CAP TS：
```
srv/server.ts
```
  中的
```
agentCard
```
- Python：
```
app/agent_card.py
```
配置
capability.sapdas.yaml
—
```
scenarios/invoke_agent.yaml
```
中的场景描述必须清晰地说明 Joule 何时应调用此 Agent。

Step 4: Deploy to Cloud Foundry

第四步：部署到 Cloud Foundry

Express (TypeScript or Python)

Express（TypeScript 或 Python）

Read

references/cf-deployment-typescript.md

references/cf-deployment.md

bash

cd <agent-name>
npm install
npm run build  # TypeScript only — must compile before push
cf push
curl https://<app-url>/.well-known/agent.json

阅读

references/cf-deployment-typescript.md

或

references/cf-deployment.md

。

bash

cd <agent-name>
npm install
npm run build  # 仅 TypeScript — 推送前必须编译
cf push
curl https://<app-url>/.well-known/agent.json

CAP (TypeScript)

CAP（TypeScript）

Read

references/cf-deployment-cap-typescript.md

bash

cd <agent-name>
npm install
mbt build
cf deploy mta_archives/<agent-name>_1.0.0.mtar
curl https://<agent-name>-srv.cfapps.<landscape>.hana.ondemand.com/.well-known/agent.json

阅读

references/cf-deployment-cap-typescript.md

。

bash

cd <agent-name>
npm install
mbt build
cf deploy mta_archives/<agent-name>_1.0.0.mtar
curl https://<agent-name>-srv.cfapps.<landscape>.hana.ondemand.com/.well-known/agent.json

Step 5: Create the BTP Destination

第五步：创建 BTP Destination

After deployment, create a BTP Destination pointing to the agent's URL:

bash

bash <skill-path>/scripts/create-destination.sh \
  --agent-name <agent-name> \
  --destination-name <DESTINATION_NAME> \
  --landscape <cf-landscape>

The destination name must match

system_aliases.<AliasName>.destination

capability.sapdas.yaml

部署后，创建一个指向 Agent URL 的 BTP Destination：

bash

bash <skill-path>/scripts/create-destination.sh \
  --agent-name <agent-name> \
  --destination-name <DESTINATION_NAME> \
  --landscape <cf-landscape>

destination 名称必须与

capability.sapdas.yaml

中的

system_aliases.<AliasName>.destination

匹配。

Step 6: Deploy the Joule Capability

第六步：部署 Joule Capability

Read

references/joule-capability.md

for the complete reference.

bash

undefined

阅读

references/joule-capability.md

获取完整参考。

bash

undefined

Install Joule CLI (if not installed)

安装 Joule CLI（如果未安装）

npm install -g @sap/joule-cli

Authenticate

认证

joule login # or joule login --use-env

joule login # 或 joule login --use-env

Navigate to the joule-capability directory

进入 joule-capability 目录

cd joule-capability

Compile + deploy

编译 + 部署

joule deploy ./da.sapdas.yaml --compile -n "<assistant_name>"

undefined

joule deploy ./da.sapdas.yaml --compile -n "<assistant_name>"

undefined

Step 7: Test the Integration

第七步：测试集成

Open Joule in your SAP system
Type a prompt that matches the capability's scenario description
Joule should route the request to your agent via A2A
Verify the response comes back correctly

If it doesn't work, check: destination configuration, agent card accessibility, capability scenario description matching, and CF app logs (

cf logs <app-name> --recent

在 SAP 系统中打开 Joule
输入一个与 capability 场景描述匹配的提示
Joule 应通过 A2A 将请求路由到你的 Agent
验证响应是否正确返回

如果不起作用，请检查：destination 配置、Agent Card 可访问性、capability 场景描述是否匹配，以及 CF 应用日志（

cf logs <app-name> --recent

）。

Modifying an Existing Agent

修改现有 Agent

When the user wants to change an existing agent:

Adding a new tool: Add the tool function, register it in the agent, add a skill to the agent card. Redeploy to CF.
Changing the model: Update
```
MODEL_NAME
```
env var. The model must be deployed on your AI Core instance.
Updating the Joule capability: Edit
```
capability.sapdas.yaml
```
and scenario files, recompile and redeploy with
```
joule deploy ./da.sapdas.yaml --compile
```
.
Scaling: Adjust
```
instances
```
and
```
memory
```
in
```
manifest.yml
```
(Express) or
```
mta.yaml
```
(CAP).

当用户想要修改现有 Agent 时：

添加新工具：添加工具函数，在 Agent 中注册，并在 Agent Card 中添加技能。重新部署到 CF。
更换模型：更新
```
MODEL_NAME
```
环境变量。模型必须已部署在 AI Core 实例上。
更新 Joule capability：编辑
```
capability.sapdas.yaml
```
和场景文件，使用
```
joule deploy ./da.sapdas.yaml --compile
```
重新编译并部署。
扩缩容：调整
```
manifest.yml
```
（Express）或
```
mta.yaml
```
（CAP）中的
```
instances
```
和
```
memory
```
。

Reference Files

参考文件

Read these before generating code:

生成代码前请阅读以下文件：

LangGraph + A2A SDK

```
references/langgraph-a2a-agent-typescript.md
```
— TypeScript Express templates (jsonRpcHandler, agentCardHandler, createReactAgent, OrchestrationClient)
```
references/langgraph-a2a-agent-cap-typescript.md
```
— TypeScript CAP templates (cds.on bootstrap, StateGraph, interrupt support)
```
references/langgraph-a2a-agent.md
```
— Python templates (A2AStarletteApplication, create_react_agent, langchain-openai with direct AI Core credentials)

```
references/langgraph-a2a-agent-typescript.md
```
— TypeScript Express 模板（jsonRpcHandler、agentCardHandler、createReactAgent、OrchestrationClient）
```
references/langgraph-a2a-agent-cap-typescript.md
```
— TypeScript CAP 模板（cds.on bootstrap、StateGraph、interrupt 支持）
```
references/langgraph-a2a-agent.md
```
— Python 模板（A2AStarletteApplication、create_react_agent、使用 AI Core 直连凭据的 langchain-openai）

Cloud Foundry Deployment

Cloud Foundry 部署

```
references/cf-deployment-typescript.md
```
— TypeScript Express: manifest.yml, package.json, cf push
```
references/cf-deployment-cap-typescript.md
```
— TypeScript CAP: mta.yaml, mbt build, cf deploy
```
references/cf-deployment.md
```
— Python: manifest.yml, requirements.txt, Procfile

```
references/cf-deployment-typescript.md
```
— TypeScript Express：manifest.yml、package.json、cf push
```
references/cf-deployment-cap-typescript.md
```
— TypeScript CAP：mta.yaml、mbt build、cf deploy
```
references/cf-deployment.md
```
— Python：manifest.yml、requirements.txt、Procfile

Joule Integration

Joule 集成

```
references/joule-capability.md
```
— Multi-file DTA format: capability.sapdas.yaml (schema 3.28.0), da.sapdas.yaml (schema 1.4.0), functions/, scenarios/, multi-turn contextId/taskId pattern

```
references/joule-capability.md
```
— 多文件 DTA 格式：capability.sapdas.yaml（schema 3.28.0）、da.sapdas.yaml（schema 1.4.0）、functions/、scenarios/、多轮 contextId/taskId 模式

Important Notes

重要说明

The A2A protocol v0.3.0 uses JSON-RPC 2.0 over HTTP(S). Your agent must handle
```
message/send
```
and optionally
```
message/stream
```
methods.
Agent Cards must be served at
```
/.well-known/agent.json
```
for Joule's discovery.
SAP GenAI Hub requires an AI Core service instance and a deployment of the model you want to use.
TypeScript agents use
```
OrchestrationClient
```
from
```
@sap-ai-sdk/langchain
```
(auto-reads VCAP_SERVICES).
Python agents use
```
langchain-openai
```
```
ChatOpenAI
```
pointed at AI Core's OpenAI-compatible endpoint (do NOT use
```
generative-ai-hub-sdk
```
— pydantic version conflict with
```
a2a-sdk
```
).

The Joule CLI (

@sap/joule-cli

) requires the

capabilityadmin

and

extensibility_developer

roles.

Destinations in BTP must use NoAuthentication or OAuth2ClientCredentials.
CAP is only available for TypeScript. Python uses Express (Starlette) only.

The

da.sapdas.yaml

uses schema version

1.4.0

. The

capability.sapdas.yaml

uses

3.28.0

Namespace must be
joule.ext
— the
```
metadata.namespace
```
in
```
capability.sapdas.yaml
```
must be set to
```
joule.ext
```
. Using any other namespace (e.g.
```
mycompany
```
) will cause
```
joule deploy
```
to fail with a namespace validation error. The scaffold scripts default to
```
joule.ext
```
.
CAP agents require two extra tools: mbt
(
```
npm install -g mbt
```
) for building and the MTA CF CLI plugin (
```
cf install-plugin multiapps
```
) for
```
cf deploy
```
to work with
```
.mtar
```
files. See CAP deploy to CF guide.

A2A 协议 v0.3.0 在 HTTP(S) 上使用 JSON-RPC 2.0。你的 Agent 必须处理
```
message/send
```
，并可选择处理
```
message/stream
```
方法。
Agent Card 必须通过
```
/.well-known/agent.json
```
提供，以便 Joule 发现。
SAP GenAI Hub 需要 AI Core 服务实例以及你想使用的模型的部署。
TypeScript Agent 使用
```
@sap-ai-sdk/langchain
```
的
```
OrchestrationClient
```
（自动读取 VCAP_SERVICES）。
Python Agent 使用
```
langchain-openai
```
的
```
ChatOpenAI
```
，指向 AI Core 的 OpenAI 兼容端点（不要使用
```
generative-ai-hub-sdk
```
——pydantic 版本与
```
a2a-sdk
```
冲突）。

Joule CLI（

@sap/joule-cli

）需要

capabilityadmin

和

extensibility_developer

角色。

BTP 中的 Destination 必须使用 NoAuthentication 或 OAuth2ClientCredentials。
CAP 仅适用于 TypeScript。Python 仅使用 Express（Starlette）。

da.sapdas.yaml

使用 schema 版本

1.4.0

。

capability.sapdas.yaml

使用

3.28.0

。

Namespace 必须为
joule.ext
—
```
capability.sapdas.yaml
```
中的
```
metadata.namespace
```
必须设置为
```
joule.ext
```
。使用任何其他 namespace（例如
```
mycompany
```
）都会导致
```
joule deploy
```
因 namespace 校验错误而失败。脚手架脚本默认使用
```
joule.ext
```
。
CAP Agent 需要两个额外工具：mbt
（
```
npm install -g mbt
```
）用于构建，以及 MTA CF CLI 插件（
```
cf install-plugin multiapps
```
）用于让
```
cf deploy
```
支持
```
.mtar
```
文件。参见 CAP 部署到 CF 指南。