AI Coding Assistant Lingma:エージェントの定義

基本概念

エージェントは「ジョブディスクリプション」と考えることができます：

エージェント自体はタスクを実行せず、単なる設定です。タスクは、そのエージェントにバインドされたセッションが実行します。

パラメーターリファレンス

モデル

model フィールドは、エージェントが使用するモデルを指定します。

ツール

tools フィールドは、ツールオブジェクトの配列です。現在、agent_toolset_20260401 ツールセットのみがサポートされています。このツールセット内のアトミックツールを有効にするには、enabled_tools 配列にリストアップします：

{
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
    }
  ]
}

enabled_tools で使用可能な値 (値は大文字と小文字が区別され、パスカルケースである必要があります)：

ツールの設定に関する詳細については、「エージェントツールの設定」をご参照ください。

エージェントの管理

CRUD API の完全なセットについては、「API リファレンス / エージェント」をご参照ください。以下の例では、一般的なワークフローを紹介します。

作成

curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "code-reviewer",
    "model": "auto",
    "instructions": "あなたはコードレビューの専門家です。コードを一行ずつレビューし、問題点と改善提案を Markdown 形式で出力してください。",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write"]
      }
    ],
    "metadata": {
      "team": "backend",
      "purpose": "code-review"
    }
  }' | jq .

リクエストが成功すると、201 Created が返されます。version は 1 から始まります。

取得

# 単一のエージェントを取得
curl -s https://api.qoder.com.cn/api/v1/cloud/agents/agent_xxx \
  -H "Authorization: Bearer $QODER_PAT"

# ページネーションでエージェントを一覧表示
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents?limit=20" \
  -H "Authorization: Bearer $QODER_PAT"

更新

エージェントを更新する際は、現在の version を指定する必要があります。詳細については、後述の「バージョン管理」をご参照ください。

curl -s -X PUT https://api.qoder.com.cn/api/v1/cloud/agents/agent_xxx \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "code-reviewer",
    "model": "auto",
    "instructions": "あなたはシニアコードレビューの専門家で、セキュリティの脆弱性とパフォーマンスの問題に重点を置いています。",
    "version": 1
  }' | jq .

リクエストが成功すると 200 OK が返され、version は自動的に 1 ずつインクリメントされます。

削除

curl -s -X DELETE https://api.qoder.com.cn/api/v1/cloud/agents/agent_xxx \
  -H "Authorization: Bearer $QODER_PAT"

エージェントを削除しても、それにバインドされているアクティブセッションは終了しません。セッションは、作成時にエージェントの設定をスナップショットとして保存します。

バージョン管理

エージェント API は、楽観的同時実行制御 (OCC) を使用します：

• version は作成時に 1 から始まります。

• 更新が成功するたびに、version は自動的に 1 ずつインクリメントされます。

• 更新リクエストには、現在の version を含める必要があります。失敗するシナリオは 2 つあります：

  • version フィールドの欠落 — 400 invalid_request_error ("Field 'version' is required.") が返されます。

  • 指定された version がサーバー側のバージョンと一致しない — 409 conflict_error が返されます。

このメカニズムにより、同時変更による上書きを防ぎます。

409 コンフリクトの処理

バージョンが古いためにリクエストが失敗した場合、次のエラーが返されます：

{
  "type": "error",
  "error": {
    "type": "conflict_error",
    "message": "Version conflict. Expected version 2, got 1."
  }
}

このコンフリクトを解決するには：

1. GET で最新のエージェントを取得し、現在の version を取得します。

2. 最新のオブジェクトデータに変更を再適用します。

3. 新しい version を使用して、再度 PUT を実行します。

ベストプラクティス

1. 命名規則 — backend-code-review や frontend-test-gen のように、team-purpose というフォーマットを使用します。

2. プロンプトの改良 — system フィールドで、役割、出力フォーマット、制約を指定します。

3. 最小権限の原則の適用：リスクを最小限に抑えるため、タスクに不可欠な tools のみを付与します。

4. メタデータの効果的な使用：キーと値のペアを使用してエージェントを分類することで、フィルタリングと監査を簡素化できます。

5. 本番環境でのバージョンのロック — セッションを作成する際、{"id": ..., "version": ...} フォーマットを使用してエージェントのバージョンをロックします。これにより、新しいバージョンがオンラインサービスに影響を与えるのを防ぎます。

よくある質問

Q：エージェントを更新すると、現在実行中のセッションに影響しますか？ いいえ。セッションは、作成時にエージェントの特定のバージョンにバインドされます。 Q：tools 配列を空にすることはできますか？ はい。tools のないエージェントは、テキストベースの対話しかできず、アクションを実行することはできません。 Q：name フィールドに長さの制限はありますか？ 64 文字以下にし、小文字、数字、ハイフンを使用することを推奨します。 Q：エージェントを古いバージョンにロールバックするにはどうすればよいですか？ 自動ロールバックはサポートされていません。更新前にエージェントの設定を保存しておくことを推奨します。元に戻すには、最新の version 番号を指定して、古い設定を手動で PUT します。