mcpField
J
joule-a2a-agent

joule-a2a-agent

github.com/sap-archiveエージェントワークフロー4283 回インストール29 週間前に更新
リポジトリ

joule-a2a-agent について

joule-a2a-agentは、SAP BTP Cloud Foundry上でSAP Joule向けのA2Aエージェントを生成・デプロイするClaude Codeスキルです。TypeScriptまたはPythonに対応し、Joule capabilityの作成とデプロイも案内します。

主な機能

  1. 01TypeScript Express／CAPのひな形
  2. 02Pythonエージェントのひな形
  3. 03A2Aプロトコルのエンドポイント設定
  4. 04Cloud Foundryへのデプロイ案内
  5. 05Joule capabilityの生成とデプロイ

活用シーン

  1. 01Joule連携エージェントのプロジェクト作成
  2. 02SAP BTP Cloud Foundryへのエージェント配置
  3. 03Joule capabilityを介した配置済みエージェントの接続

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/sap-archive/joule-a2a-agent-toolkit --skill joule-a2a-agent

インストール後、Claude Code で/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 ExpressTS CAPPython
サーバーExpress + jsonRpcHandler/agentCardHandlerCAP + cds.on("bootstrap")Starlette + A2AStarletteApplication
A2A SDK@a2a-js/sdk 0.3.10@a2a-js/sdk 0.3.10a2a-sdk >=0.2.7
LLMOrchestrationClientOrchestrationClientlangchain-openai ChatOpenAI（AI Core エンドポイントに直接接続）
デプロイcf push (manifest.yml)mbt build && cf deploy (mta.yaml)cf push (manifest.yml)
認証手動CAP に組み込み手動
エージェントのパターンcreateReactAgentStateGraph（手動）create_react_agent
割り込みのサポート基本（質問のヒューリスティック）完全（LangGraph interrupt()）構造化レスポンス形式
ビルドパックnodejs_buildpacknodejs_buildpack（MTA 経由）python_buildpack
リファレンスlanggraph-a2a-agent-typescript.mdlanggraph-a2a-agent-cap-typescript.mdlanggraph-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 にデプロイするガイドを参照してください。

コメント

Markdown 対応