はじめに
IBM watsonx Orchestrate ADK（Agent Development Kit）を使って、プロジェクト管理ツールの Backlog と連携する AI Agent を作成してみました。この記事では、実際に動作するコードと手順を紹介します。
前提条件
watsonx Orchestrate ADK の環境と Backlog の環境は構築済みとします。ADK の環境構築については以下を参照してください
今回作成するもの
Backlog の課題（Issue）を取得する AI Agent を作成します。この Agent は以下の機能を持ちます。
- Backlog の全課題を取得
- 特定のプロジェクトに絞った課題の取得
- 課題の詳細情報（ステータス、優先度、担当者など）の表示
実装手順
1. Backlog との接続設定
まず、watsonx Orchestrate ADK に Backlog への接続情報を設定します：
# Backlog コネクションの追加
orchestrate connections add -a backlog
# 接続設定の構成
orchestrate connections configure -a backlog --env draft --kind key_value --type team
# 認証情報の設定
orchestrate connections set-credentials -a backlog --env draft -e host=https://xxx.backlog.com -e apikey=xxx
設定項目の説明：
-
host: Backlog のベース URL（https://your-space.backlog.com） -
apikey: Backlog で発行した API キー
yaml でも設定できますが、ここではコマンドで設定しました。
2. 必要なパッケージの定義
Python ツールで使用するパッケージを requirements.txt に定義します：
requests==2.32.3
3. Python ツールの実装
Backlog の課題を取得する Python ツールを実装します：
from typing import List, Optional, Dict, Any
import requests
from ibm_watsonx_orchestrate.agent_builder.tools import tool
from ibm_watsonx_orchestrate.run import connections
from ibm_watsonx_orchestrate.client.connections import ConnectionType
CONNECTION_BACKLOG = 'backlog'
CONNECTION_BACKLOG_HOST = 'host'
CONNECTION_BACKLOG_APIKEY = 'apikey'
@tool(
expected_credentials=[
{"app_id": 'backlog', "type": ConnectionType.KEY_VALUE}
]
)
def get_backlog_issues(project_id: Optional[int] = None) -> List[Dict[str, Any]]:
"""
Fetch issues from Backlog.
:param project_id: Optional project ID to filter issues by project
:returns: List of Backlog issues with details
"""
# 接続情報の取得
base_url = connections.key_value(CONNECTION_BACKLOG)[
CONNECTION_BACKLOG_HOST]
url = f"{base_url}/api/v2/issues"
headers = {
'Accept': 'application/json'
}
# Backlog APIのパラメータ設定
query_params = {
'apiKey': connections.key_value(CONNECTION_BACKLOG)[CONNECTION_BACKLOG_APIKEY]
}
# オプションパラメータの追加
if project_id:
query_params['projectId[]'] = project_id
# Backlog API の呼び出し
response = requests.get(
url,
headers=headers,
params=query_params
)
response.raise_for_status()
data = response.json()
# レスポンスの簡略化
simplified_issues = []
for issue_data in data:
simplified_issue = {
'id': issue_data['id'],
'issueKey': issue_data['issueKey'],
'keyId': issue_data['keyId'],
'summary': issue_data['summary'],
'description': issue_data.get('description'),
'status': issue_data['status']['name'],
'priority': issue_data['priority']['name'],
'issueType': issue_data['issueType']['name'],
'assignee': issue_data['assignee']['name'] if issue_data.get('assignee') else None,
'created': issue_data['created'],
'updated': issue_data['updated'],
'startDate': issue_data.get('startDate'),
'dueDate': issue_data.get('dueDate'),
'estimatedHours': issue_data.get('estimatedHours'),
'actualHours': issue_data.get('actualHours'),
'category': [cat['name'] for cat in issue_data.get('category', [])],
'versions': [ver['name'] for ver in issue_data.get('versions', [])],
'milestone': [mile['name'] for mile in issue_data.get('milestone', [])]
}
simplified_issues.append(simplified_issue)
return simplified_issues
コードの解説：
@tool デコレータで watsonx Orchestrate ADK のツールとして関数を定義しています。expected_credentials パラメータで必要な認証情報を指定することで、事前に設定した接続情報を自動的に利用できます。
connections.key_value() を使用して、事前に設定した接続情報を安全に取得しています。API キーなどの機密情報がコード内にハードコーディングされることを防げます。
response.raise_for_status() を使用して、HTTP エラーが発生した場合に適切な例外を発生させています。
Backlog API のレスポンスは非常に詳細なため、AI Agent が処理しやすいよう必要な情報のみを抽出して返却しています。
4. ツールのデプロイ
実装したツールを watsonx Orchestrate ADK にデプロイします：
orchestrate tools import -k python -f ./tools/get_backlog_issues.py -r ./tools/requirements.txt --app-id backlog
5. Agent の定義
ツールを呼び出す Agent の定義を行います（詳細な手順は省略）。Agent は自然言語での指示を受け取り、適切なツールを選択して実行します。
使用例
デプロイ後、以下のような自然言語で AI Agent に指示できます：
- "Backlog の課題を教えて"
- "プロジェクト ID 123 の課題を取得して"
- "未完了の課題はありますか？"
まとめ
IBM watsonx Orchestrate ADK を使用することで、比較的簡単に Backlog と連携する AI Agent を作成できました。このパターンは他の REST API を持つサービスにも応用できるため、様々な業務システムとの連携が可能になります。
今後は課題の作成や更新機能も追加して、より実用的な AI Agent に発展させていきたいと思います。
参考