joule-a2a-agent

SAP BTP Cloud Foundry 上の Joule A2A エージェント

このスキルは、次の機能を備えた完全なプロコード AI エージェントプロジェクトを生成します。

1. LangGraph + @a2a-js/sdk 0.3.10 と、LLM プロバイダーとして SAP GenAI Hub（OrchestrationClient）を使用し、A2A プロトコル v0.3.0 をサポートするエージェントを実装します
2. SAP BTP Cloud Foundry に REST API としてデプロイします（cf push または MTA 経由）
3. 複数ファイル形式の DTA を使用し、A2A アクションを含む Joule capability を作成します
4. capability をコンパイルし、Joule にデプロイする CLI コマンドを提供します

仕組み — 全体像

SAP Joule は、A2A（Agent-to-Agent）プロトコルを使用して外部エージェントをオーケストレーションできます。処理の流れは次のとおりです。

1. エージェントは Cloud Foundry 上で TypeScript または Python の Web サービスとして実行され、A2A 互換エンドポイントを公開します
2. Joule は Agent Card を読み取ってエージェントを検出します。Agent Card は /.well-known/agent.json にあります
3. ユーザーのプロンプトがエージェントの capability に一致すると、Joule は A2A タスクをエージェントに送信します
4. エージェントは LangGraph（ツール、SAP GenAI Hub 経由の LLM 推論など）を使用してリクエストを処理し、結果を返します
5. Joule は結果をチャットでユーザーに表示します

Joule とエージェントの接続には、BTP Destination と、agent-request アクションタイプを定義する Joule capability YAML を使用します。

前提条件

Joule DTA スキーマバージョン 3.28.0 以降が必要です： agent-request アクションタイプを使用するコードベースのエージェント（BYOA）は、DTA スキーマバージョン 3.28.0 以降でサポートされています。capability.sapdas.yaml には schema_version: "3.28.0" を指定する必要があります。

Joule テナントで古いスキーマバージョンが実行されている場合、コンパイルは成功しますが、デプロイは次のエラーで失敗します：「設定ファイルで定義されたスキーマバージョンが、Joule の現在のスキーマバージョンより新しい」。

テナントのバージョンを確認する方法：

1. ログインします：joule login --use-env（または joule login ）
2. ステータスを確認します：joule status
3. デプロイを試します。スキーマエラーが発生した場合、テナントの更新が必要です
4. BTP 管理者に連絡し、Joule サービスの更新を依頼します

その他の前提条件：

• Cloud Foundry が有効になっている SAP BTP サブアカウント
• GenAI Hub モデルをデプロイした AI Core サービスインスタンス
• 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 ロール：Joule のデプロイには extensibility_developer と capabilityadmin
• CAP エージェントの場合：mbt（MTA Build Tool）：npm install -g mbt
• CAP エージェントの場合：MTA CF CLI プラグイン：cf install-plugin multiapps（.mtar ファイルを使った cf deploy に必要）

開始する前に、Claude Code がツールキットプラグインとともに起動しており、両方の CLI にログインしていることを確認してください。

# Start Claude Code with the SAP A2A Agent Toolkit plugin
claude --plugin-dir <path-to-sap-a2a-agent-toolkit>

# Log in to Cloud Foundry
cf login -a https://api.cf.<landscape>.hana.ondemand.com 

# Log in to Joule
joule login 

ワークフロー

ユーザーから Joule A2A エージェントの作成または変更を依頼された場合は、次の手順に従います。

ステップ 1：要件の確認

ユーザーに次の内容を尋ねます。

• 言語 — TypeScript（デフォルト）または Python
• フレームワーク — Express（デフォルト、軽量）または CAP（エンタープライズ向け、MTA デプロイ）。注：CAP は TypeScript のみです
• エージェント名と目的 — このエージェントで何をするか
• ツール／API — エージェントが呼び出す外部サービスや API
• SAP GenAI Hub モデル — AI Core にデプロイされているモデル（デフォルト：gpt-4.1）
• BTP ランドスケープの詳細 — CF API エンドポイント、組織、スペース（わかる場合）

BTP の詳細が不明な場合は、プレースホルダー値を使ってプロジェクトを生成します。

ステップ 2：エージェントプロジェクトの生成

プロジェクトは、次の 3 種類の構成で生成できます。

a) TypeScript + Express（デフォルト）

スキャフォールドスクリプトを実行します。

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 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

b) TypeScript + CAP

スキャフォールドスクリプトを実行します。

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 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

c) Python + Express

スキャフォールドスクリプトを実行します：

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 を使用して手動で設定します。

主な違い

項目	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 に組み込み	手動
エージェントのパターン	createReactAgent	StateGraph（手動）	create_react_agent
割り込みのサポート	基本（質問のヒューリスティック）	完全（LangGraph interrupt()）	構造化レスポンス形式
ビルドパック	nodejs_buildpack	nodejs_buildpack（MTA 経由）	python_buildpack
リファレンス	langgraph-a2a-agent-typescript.md	langgraph-a2a-agent-cap-typescript.md	langgraph-a2a-agent.md

Joule の機能 YAML ファイルは、言語やフレームワークに関係なく同一です。

ステップ 3：エージェントをカスタマイズする

ユーザーの要件に基づいて、次のように設定します。

1. ツールを定義する — TypeScript では tool() と Zod スキーマを使用して関数を作成します。Python では @tool デコレーターを使用します。各ユーザー要件をツール関数に対応付けます。

   • Express TS：src/tools.ts
   • CAP TS：srv/tools/tools.ts
   • Python：app/tools.py

2. エージェントを設定する — エージェントの目的に合わせてシステム指示を設定します。

   • Express TS：src/agent.ts の SYSTEM_PROMPT
   • CAP TS：srv/utils/prompts.ts
   • Python：app/agent.py の SYSTEM_INSTRUCTION

3. Agent Card を設定する — 名前、スキル、サポートするモードを設定します。

   • Express TS：src/agentCard.ts
   • CAP TS：srv/server.ts の agentCard
   • Python：app/agent_card.py

4. capability.sapdas.yaml を設定する — scenarios/invoke_agent.yaml のシナリオの説明には、Joule がこのエージェントを呼び出すタイミングを明確に記述する必要があります。

ステップ 4：Cloud Foundry にデプロイする

Express（TypeScript または Python）

references/cf-deployment-typescript.md または references/cf-deployment.md を参照してください。

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

CAP（TypeScript）

references/cf-deployment-cap-typescript.md を参照してください。

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

ステップ 5：BTP 宛先を作成する

デプロイ後、エージェントの URL を指す BTP 宛先を作成します。

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

宛先名は、capability.sapdas.yaml の system_aliases.<AliasName>.destination と一致している必要があります。

ステップ 6：Joule の機能をデプロイする

完全なリファレンスについては、references/joule-capability.md を参照してください。

# Install Joule CLI (if not installed)
npm install -g @sap/joule-cli

# Authenticate
joule login     # or joule login --use-env

# Navigate to the joule-capability directory
cd joule-capability

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

ステップ 7：統合をテストする

1. SAP システムで Joule を開きます
2. 機能のシナリオの説明に一致するプロンプトを入力します
3. Joule が A2A 経由でリクエストをエージェントにルーティングすることを確認します
4. レスポンスが正しく返されることを確認します

動作しない場合は、宛先の設定、Agent Card へのアクセス、機能のシナリオの説明との一致、および CF アプリのログ（cf logs <app-name> --recent）を確認してください。

既存のエージェントを変更する

既存のエージェントを変更する場合：

1. 新しいツールを追加する：ツール関数を追加してエージェントに登録し、Agent Card にスキルを追加します。CF に再デプロイします。

2. モデルを変更する：MODEL_NAME 環境変数を更新します。モデルは AI Core インスタンスにデプロイされている必要があります。

3. Joule の機能を更新する：capability.sapdas.yaml とシナリオファイルを編集し、joule deploy ./da.sapdas.yaml --compile で再コンパイルして再デプロイします。

4. スケーリングする：manifest.yml（Express）または mta.yaml（CAP）の instances と memory を調整します。

リファレンスファイル

コードを生成する前に、以下を参照してください。

LangGraph + A2A SDK

• references/langgraph-a2a-agent-typescript.md — TypeScript Express テンプレート（jsonRpcHandler、agentCardHandler、createReactAgent、OrchestrationClient）
• references/langgraph-a2a-agent-cap-typescript.md — TypeScript CAP テンプレート（cds.on によるブートストラップ、StateGraph、中断のサポート）
• references/langgraph-a2a-agent.md — Python テンプレート（A2AStarletteApplication、create_react_agent、AI Core の認証情報を直接使用する langchain-openai）

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

Joule との統合

• references/joule-capability.md — 複数ファイルからなる DTA 形式：capability.sapdas.yaml（schema 3.28.0）、da.sapdas.yaml（schema 1.4.0）、functions/、scenarios/、複数ターンの contextId/taskId パターン

重要な注意事項

• A2A プロトコル v0.3.0 は、HTTP(S) 上で JSON-RPC 2.0 を使用します。エージェントは message/send メソッドと、必要に応じて message/stream メソッドを処理する必要があります。
• Joule の検出用に、Agent Card を /.well-known/agent.json で提供する必要があります。
• SAP GenAI Hub を使用するには、AI Core サービスインスタンスと、使用するモデルのデプロイが必要です。
• TypeScript エージェントは、@sap-ai-sdk/langchain の OrchestrationClient を使用します（VCAP_SERVICES を自動的に読み取ります）。
• Python エージェントは、AI Core の OpenAI 互換エンドポイントを指定した langchain-openai の ChatOpenAI を使用します（a2a-sdk と pydantic のバージョンが競合するため、generative-ai-hub-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）を使用すると、Namespace の検証エラーが発生して joule deploy が失敗します。スキャフォールドスクリプトのデフォルト値は joule.ext です。
• CAP エージェントでビルドを行うには mbt（npm install -g mbt）、.mtar ファイルを使用して cf deploy を実行するには MTA CF CLI プラグイン（cf install-plugin multiapps）という、2 つの追加ツールが必要です。CAP を CF にデプロイするガイドを参照してください。