リサーチタスクを計画

リサーチタスクを作成せずに見積もります。決定された検索の深度と、コスト、レイテンシ、作業量の見積もりを返し、見積もりが提示された予算に収まるかどうかも示します。

計画、作成、ポーリング、結果の読み取りの流れについては、リサーチタスクの実行を参照してください。

1 min read

post/knowledge-fs/spaces/{knowledge_base_id}/research-tasks/plan

Request example

curl --request POST \
  --url https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/research-tasks/plan \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "budgetUsd": 0.05,
  "mode": "research",
  "query": "What changed in the 2025 refund policy, and which regions are affected?",
  "topK": 10
}'

import requests

url = "https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/research-tasks/plan"
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json",
}
payload = {
    "budgetUsd": 0.05,
    "mode": "research",
    "query": "What changed in the 2025 refund policy, and which regions are affected?",
    "topK": 10
}

response = requests.request("POST", url, headers=headers, json=payload)

print(response.text)

const response = await fetch('https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/research-tasks/plan', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "budgetUsd": 0.05,
    "mode": "research",
    "query": "What changed in the 2025 refund policy, and which regions are affected?",
    "topK": 10
  })
});

const data = await response.json();
console.log(data);

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/research-tasks/plan',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => '{
  "budgetUsd": 0.05,
  "mode": "research",
  "query": "What changed in the 2025 refund policy, and which regions are affected?",
  "topK": 10
}',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer <token>',
    'Content-Type: application/json',
  ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	url := "https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/research-tasks/plan"
	payload := strings.NewReader("{\n  \"budgetUsd\": 0.05,\n  \"mode\": \"research\",\n  \"query\": \"What changed in the 2025 refund policy, and which regions are affected?\",\n  \"topK\": 10\n}")

	req, _ := http.NewRequest("POST", url, payload)
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))
}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/research-tasks/plan"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"budgetUsd\": 0.05,\n  \"mode\": \"research\",\n  \"query\": \"What changed in the 2025 refund policy, and which regions are affected?\",\n  \"topK\": 10\n}"))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

require 'uri'
require 'net/http'

url = URI('https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/research-tasks/plan')

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = url.scheme == 'https'

request = Net::HTTP::Post.new(url)
request['Authorization'] = 'Bearer <token>'
request['Content-Type'] = 'application/json'
request.body = '{
  "budgetUsd": 0.05,
  "mode": "research",
  "query": "What changed in the 2025 refund policy, and which regions are affected?",
  "topK": 10
}'

response = http.request(request)
puts response.read_body

Response

{
  "budget": {
    "budget_usd": 0.05,
    "exceeds_budget": false,
    "remaining_budget_usd": 0.018238
  },
  "estimates": {
    "cacheHitProbability": 0.25,
    "costUsd": {
      "currency": "USD",
      "estimated": 0.031762,
      "max": 0.042879,
      "min": 0.020645
    },
    "inputTokens": 3070,
    "latencyMs": {
      "p50": 2800,
      "p95": 5040
    },
    "outputTokens": 1776,
    "retrievalSteps": 3,
    "scannedResources": 620,
    "toolCalls": 6,
    "totalTokens": 4846,
    "workBounds": {
      "modelCalls": {
        "estimated": 3,
        "max": 4,
        "min": 2
      },
      "openedResources": {
        "estimated": 20,
        "max": 40,
        "min": 0
      },
      "retrievalSteps": {
        "estimated": 3,
        "max": 5,
        "min": 1
      }
    }
  },
  "knowledge_space_id": "b2f1d3a4-5e6c-4a7b-8c9d-0e1f2a3b4c5d",
  "query": "What changed in the 2025 refund policy, and which regions are affected?",
  "retrieval_plan": {
    "dense_top_k": 100,
    "fts_top_k": 100,
    "fusion_limit": 50,
    "query_language": "latin",
    "requested_mode": "research",
    "rerank_candidate_limit": 50,
    "resolved_mode": "research",
    "strategy_version": "retrieval-planner-v2",
    "top_k": 10
  },
  "steps": [
    {
      "estimatedCostUsd": 0.003126,
      "estimatedInputTokens": 274,
      "estimatedLatencyMs": 350,
      "estimatedOutputTokens": 192,
      "estimatedToolCalls": 1,
      "name": "plan"
    },
    {
      "estimatedCostUsd": 0.00124,
      "estimatedInputTokens": 0,
      "estimatedLatencyMs": 600,
      "estimatedOutputTokens": 0,
      "estimatedToolCalls": 3,
      "name": "retrieve"
    },
    {
      "estimatedCostUsd": 0.007542,
      "estimatedInputTokens": 978,
      "estimatedLatencyMs": 650,
      "estimatedOutputTokens": 384,
      "estimatedToolCalls": 1,
      "name": "analyze"
    },
    {
      "estimatedCostUsd": 0.019854,
      "estimatedInputTokens": 1818,
      "estimatedLatencyMs": 1200,
      "estimatedOutputTokens": 1200,
      "estimatedToolCalls": 1,
      "name": "generate"
    }
  ],
  "strategy_version": "research-dry-run-planner-v1"
}

{
  "code": "knowledge_fs_invalid_request",
  "message": "Agent Knowledge Base request is invalid.",
  "status": 400,
  "violations": [
    {
      "field": [
        "limits"
      ],
      "type": "extra_forbidden"
    }
  ]
}

{
  "code": "knowledge_fs_invalid_request",
  "failure": {
    "category": "validation",
    "code": "KNOWLEDGE_FS_INVALID_REQUEST",
    "message": "The Agent Knowledge Base request is invalid.",
    "retryPolicy": "never",
    "traceId": "d44c6dd1-da9c-46e7-81e1-5f09707c4352"
  },
  "message": "The Agent Knowledge Base request is invalid.",
  "status": 400
}

{
  "code": "knowledge_fs_invalid_credential",
  "message": "Invalid Agent Knowledge Base service credential.",
  "status": 401
}

{
  "code": "unauthorized",
  "message": "Access token is invalid",
  "status": 401
}

{
  "code": "forbidden",
  "message": "Sorry, you have reached the knowledge base request rate limit of your subscription.",
  "status": 403
}

{
  "code": "knowledge_fs_access_denied",
  "message": "Agent Knowledge Base operation is not allowed.",
  "status": 403
}

{
  "code": "knowledge_fs_resource_not_found",
  "failure": {
    "category": "not_found",
    "code": "KNOWLEDGE_FS_NOT_FOUND",
    "message": "The requested Agent Knowledge Base resource was not found.",
    "retryPolicy": "never",
    "traceId": "8f3a2c14-9d6b-4c07-b5a1-2e7d0c93f5b2"
  },
  "message": "The requested Agent Knowledge Base resource was not found.",
  "status": 404
}

{
  "code": "not_found",
  "message": "The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again.",
  "status": 404
}

{
  "code": "knowledge_fs_request_too_large",
  "message": "Agent Knowledge Base request is too large.",
  "status": 413
}

{
  "code": "knowledge_fs_upstream_unavailable",
  "failure": {
    "action": "contact_admin",
    "category": "internal",
    "code": "KNOWLEDGE_FS_INTERNAL_ERROR",
    "message": "Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference.",
    "retryPolicy": "manual",
    "traceId": "5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b"
  },
  "message": "Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference.",
  "status": 502
}

{
  "code": "knowledge_fs_upstream_unavailable",
  "message": "Agent Knowledge Base is unavailable.",
  "status": 502
}

{
  "code": "knowledge_fs_operation_unavailable",
  "message": "Agent Knowledge Base operation is not available.",
  "status": 503
}

{
  "code": "knowledge_fs_operation_unavailable",
  "failure": {
    "action": "retry",
    "category": "dependency",
    "code": "KNOWLEDGE_FS_UNAVAILABLE",
    "message": "A service required by Agent Knowledge Base is temporarily unavailable.",
    "retryPolicy": "manual",
    "traceId": "5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b"
  },
  "message": "A service required by Agent Knowledge Base is temporarily unavailable.",
  "status": 503
}

post/knowledge-fs/spaces/{knowledge_base_id}/research-tasks/plan

Authorization

Authorizationstringheaderrequired#

すべてのリクエストは API キーで認証します：Authorization: Bearer {API_KEY}。アプリのエンドポイントにはアプリの API キーを、ナレッジのエンドポイントにはナレッジベースの API キーを使用します（Dify API クイックスタート）。

キーはサーバーサイドで保管し、クライアントコードには決して埋め込まないでください。キーが欠落または無効なリクエストは HTTP 401（unauthorized）で失敗します。

Path parameters

knowledge_base_idstringrequired#

ナレッジベース ID です。ナレッジベースの API アクセス ダイアログに表示されるサービス API エンドポイントの最後のセグメント（…/knowledge-fs/spaces/<knowledge base ID>）です。アドレスバーでは /datasets/new/ の後のセグメントです。

Body

application/json

budgetUsdnumber#

コストの見積もりと比較する支出の上限（USD）です。レスポンスの budget.exceeds_budget と budget.remaining_budget_usd に反映されます。

Range: >= 0

modeenum<string>#

検索の深度です。fast、deep、research のいずれかを指定します（検索の深度を参照）。省略すると、ナレッジベースのデフォルトの深度が使われます。これはナレッジベース設定を取得の retrieval.default_mode です。

Options:fastdeepresearchnull

querystringrequired#

質問です。空白のみではないクエリを指定してください。また、UTF-8 で 16,384 バイトまでに制限されます。

Length: max 16000Pattern: \S

topKinteger#

検索結果をマージしてリランクした後に残すチャンクの最大数です。明示的に指定する場合は 1〜50 の値にしてください。省略すると、ナレッジベースで公開されている トップ K 設定（最大 100）が使われます。値を大きくするとモデルに渡るコンテキストが増えますが、ノイズも増えます。値を小さくすると焦点は絞られますが、関連するチャンクを取りこぼすことがあります。

Range: 1–50

Responses

application/json

計画とその見積もりです。

budgetobject#

リクエストの budgetUsd に対するコスト見積もりの判定結果です。

Show child attributes

budget_usdnumber#

リクエストの budgetUsd です。送信されなかった場合は null です。

exceeds_budgetboolean#

estimates.costUsd.estimated が budgetUsd を上回る場合は true です。予算がない場合は常に false です。この値は参考情報にすぎません。リサーチタスクを作成は、この場合もタスクを受け付け、次のモデル呼び出しで予算を超える可能性が生じた時点でキャンセルします。

remaining_budget_usdnumber#

budgetUsd から見積もりコストを引いた値です。予算を超える場合は負の値になります。予算がない場合は null です。

estimatesobject#

タスクの作業量、コスト、レイテンシの見積もりです。リサーチタスクを作成に送信する予定の limits と比較してください。

Show child attributes

cacheHitProbabilitynumber#

キャッシュから返される検索の割合の見積もりで、0 から 1 までの値です。

costUsdobject#

タスクの見積もりコストです。

Show child attributes

currencystring#

常に USD です。

estimatednumber#

点推定値（USD）です。

maxnumber#

上限値（USD）です。

minnumber#

下限値（USD）です。

inputTokensinteger#

全ステップでのモデル入力トークン数の見積もりです。

latencyMsobject#

開始から完了までの所要時間の見積もり（ミリ秒）です。リサーチタスクを取得の最初のポーリングのタイミングは、p50 をもとに決めてください。

Show child attributes

p50integer#

中央値の見積もりです。

p95integer#

95 パーセンタイルの見積もりです。この値が limits.timeoutMs と照合されます。

outputTokensinteger#

全ステップでのモデル出力トークン数の見積もりです。

retrievalStepsinteger#

検索ラウンド数の見積もりです。limits.maxRetrievalSteps と照合されます。

scannedResourcesinteger#

読み取るドキュメントとセクションの数の見積もりです。limits.maxScannedResources と照合されます。

toolCallsinteger#

ツール呼び出し回数の見積もりです。limits.maxToolCalls と照合されます。

totalTokensinteger#

inputTokens と outputTokens の合計です。

workBoundsobject#

点推定値の根拠となる範囲です。リサーチタスクを作成がチェックするのは、これらの範囲ではなく点推定値です。

Show child attributes

modelCallsobject#

モデル呼び出し回数の見積もり値、最小値、最大値です。

Show child attributes

estimatedinteger#

点推定値です。

maxinteger#

上限値です。

mininteger#

下限値です。

openedResourcesobject#

開くドキュメントとセクションの数の見積もり値、最小値、最大値です。

Show child attributes

estimatedinteger#

点推定値です。

maxinteger#

上限値です。

mininteger#

下限値です。

retrievalStepsobject#

検索ラウンド数の見積もり値、最小値、最大値です。

Show child attributes

estimatedinteger#

点推定値です。

maxinteger#

上限値です。

mininteger#

下限値です。

knowledge_space_idstring#

ナレッジベースの内部 ID です。パスのナレッジベース ID とは異なります。

querystring#

前後の空白を取り除いた質問です。

retrieval_planobject#

検索をどのように実行するかを示します。

Show child attributes

dense_top_kinteger#

ベクトル検索から取得する候補数です。

fts_top_kinteger#

キーワード検索から取得する候補数です。

fusion_limitinteger#

ベクトル検索とキーワード検索の結果をマージした後に残す候補数です。

query_languagestring#

検出された質問の言語で、cjk、latin、mixed-cjk-latin、other のいずれかです。

requested_modestring#

リクエストの mode です。省略した場合はナレッジベースのデフォルトの深度です。fast、deep、research のいずれかです。

rerank_candidate_limitinteger#

リランクモデルに渡す候補数です。

resolved_modestring#

実行される深度で、fast、deep、research のいずれかです。リサーチタスクを作成にも同じ mode を送信してください。そこで異なる深度を指定すると、limits は別の見積もりと照合されます。

strategy_versionstring#

この計画を作成した検索戦略のバージョンです。

top_kinteger#

検索結果をマージしてリランクした後に残すチャンクの最大数です。

stepsobject[]#

ステップごとの見積もりです。実行順に並びます。

Show child attributes

estimatedCostUsdnumber#

ステップの見積もりコスト（USD）です。

estimatedInputTokensinteger#

モデル入力トークン数の見積もりです。

estimatedLatencyMsinteger#

所要時間の見積もり（ミリ秒）です。

estimatedOutputTokensinteger#

モデル出力トークン数の見積もりです。

estimatedToolCallsinteger#

ツール呼び出し回数の見積もりです。

namestring#

ステップ名です。plan、retrieve、analyze、generate は常にこの順で含まれます。検索戦略がドキュメントのアウトラインを読む場合は、plan の後に inspect が続きます。

strategy_versionstring#

見積もりロジックのバージョンです。

リサーチタスクを作成リサーチタスクを取得