AIエージェントの無限ループを防ぐ方法｜最大ステップ数・予算・終了条件

十分な情報が集まったら終了してください

ユーザー
↓
LLM
↓
回答

ユーザー
↓
LLM
↓
search_web
↓
検索結果
↓
LLM
↓
read_page
↓
取得結果
↓
LLM
↓
最終回答

検索
↓
検索
↓
検索
↓
検索
↓
検索

const MAX_STEPS = 10;

for (
  let step = 0;
  step < MAX_STEPS;
  step += 1
) {
  const response =
    await callModel();

  if (
    response.type === "final"
  ) {
    return response;
  }

  await executeTools(
    response.toolCalls,
  );
}

throw new Error(
  "最大ステップ数に達しました。",
);

最大10回までツールを使ってください

import {
  Agent,
  MaxTurnsExceededError,
  run,
} from "@openai/agents";

const agent =
  new Agent({
    name: "Research Agent",
    instructions: `
必要な情報だけを調査し、
十分な根拠が集まったら
最終回答を返してください。
    `.trim(),
  });

try {
  const result =
    await run(
      agent,
      "Node.jsの最新仕様を調べて",
      {
        maxTurns: 8,
      },
    );

  console.log(
    result.finalOutput,
  );
} catch (error) {
  if (
    error instanceof
    MaxTurnsExceededError
  ) {
    console.error(
      "最大ターン数に達しました。",
    );
  } else {
    throw error;
  }
}

maxTurns: null

正常完了した処理のステップ数

p95のステップ数

上限到達率

1タスク当たり料金

search_google
search_bing
search_database
search_internal_wiki

maxSteps

maxToolCalls

type AgentLimits = {
  maxSteps: number;
  maxToolCalls: number;
};

const limits:
  AgentLimits = {
    maxSteps: 10,
    maxToolCalls: 20,
  };

let toolCallCount = 0;

async function executeTool(
  call: ToolCall,
) {
  toolCallCount += 1;

  if (
    toolCallCount >
    limits.maxToolCalls
  ) {
    throw new Error(
      "ツール実行回数の上限に達しました。",
    );
  }

  return runTool(call);
}

const TOOL_LIMITS:
  Record<string, number> = {
  search_web: 8,
  read_page: 12,
  query_database: 5,
  send_email: 1,
  create_order: 1,
};

const toolCounts =
  new Map<string, number>();

function checkToolLimit(
  toolName: string,
): void {
  const current =
    toolCounts.get(
      toolName,
    ) ?? 0;

  const next =
    current + 1;

  const limit =
    TOOL_LIMITS[
      toolName
    ] ?? 5;

  if (next > limit) {
    throw new Error(
      `${toolName}の実行上限に達しました。`,
    );
  }

  toolCounts.set(
    toolName,
    next,
  );
}

search_web({
  query: "Node.js latest version"
})

search_web({ query: "OpenAI Agents SDK" })
search_web({ query: "Claude Agent SDK" })
search_web({ query: "Gemini Function Calling" })

toolName

toolName
+
normalized arguments

page=1
page=2
page=3

page=3
page=3
page=3

LLM
↓
get_customer
↓
500 Error
↓
LLM
↓
get_customer
↓
500 Error
↓
LLM
↓
get_customer

type ToolResult =
  | {
      ok: true;
      data: unknown;
    }
  | {
      ok: false;
      retryable: boolean;
      error: string;
    };

{
  "ok": false,
  "retryable": false,
  "error": "customer_id is invalid"
}

retryable=falseのツールエラーを
同じ引数で再試行してはいけません。

type AgentBudget = {
  maxCostUsd: number;
};

const budget:
  AgentBudget = {
    maxCostUsd: 0.50,
  };

let totalCostUsd = 0;

function recordCost(
  costUsd: number,
): void {
  totalCostUsd += costUsd;

  if (
    totalCostUsd >
    budget.maxCostUsd
  ) {
    throw new Error(
      "AIエージェントの料金上限に達しました。",
    );
  }
}

import {
  query,
} from "@anthropic-ai/claude-agent-sdk";

for await (
  const message
  of query({
    prompt:
      "リポジトリを調査して原因を特定してください。",
    options: {
      maxTurns: 12,
      maxBudgetUsd: 0.50,
    },
  })
) {
  console.log(
    message,
  );
}

type TokenBudget = {
  maxInputTokens: number;
  maxOutputTokens: number;
  maxTotalTokens: number;
};

const tokenBudget:
  TokenBudget = {
    maxInputTokens:
      100_000,

    maxOutputTokens:
      30_000,

    maxTotalTokens:
      130_000,
  };

let inputTokens = 0;
let outputTokens = 0;

function recordUsage(
  usage: {
    inputTokens: number;
    outputTokens: number;
  },
): void {
  inputTokens +=
    usage.inputTokens;

  outputTokens +=
    usage.outputTokens;

  const totalTokens =
    inputTokens +
    outputTokens;

  if (
    inputTokens >
      tokenBudget
        .maxInputTokens ||
    outputTokens >
      tokenBudget
        .maxOutputTokens ||
    totalTokens >
      tokenBudget
        .maxTotalTokens
  ) {
    throw new Error(
      "トークン予算を超えました。",
    );
  }
}

残り予算が少ないので
そろそろまとめてください

上限を超えたので
アプリケーションが強制停止

const MAX_DURATION_MS =
  90_000;

const startedAt =
  Date.now();

function checkDuration():
  void {
  const elapsed =
    Date.now() -
    startedAt;

  if (
    elapsed >
    MAX_DURATION_MS
  ) {
    throw new Error(
      "エージェントの最大実行時間に達しました。",
    );
  }
}

checkDuration();

const modelResponse =
  await callModel();

checkDuration();

const toolResult =
  await executeTool();

const signal =
  AbortSignal.timeout(
    90_000,
  );

const result =
  await run(
    agent,
    userInput,
    {
      maxTurns: 10,
      signal,
    },
  );

async function searchWeb(
  query: string,
  signal: AbortSignal,
) {
  return fetch(
    createSearchUrl(query),
    {
      signal,
    },
  );
}

async function executeToolWithTimeout(
  call: ToolCall,
): Promise<unknown> {
  const signal =
    AbortSignal.timeout(
      10_000,
    );

  return executeTool(
    call,
    signal,
  );
}

step 1: 検索結果Aを取得
step 2: 検索結果Aを取得
step 3: 検索結果Aを取得

import {
  createHash,
} from "node:crypto";

function stableJson(
  value: unknown,
): string {
  if (
    value === null ||
    typeof value !== "object"
  ) {
    return JSON.stringify(
      value,
    );
  }

  if (Array.isArray(value)) {
    return (
      "[" +
      value
        .map(stableJson)
        .join(",") +
      "]"
    );
  }

  const object =
    value as
      Record<string, unknown>;

  const keys =
    Object.keys(object)
      .sort();

  return (
    "{" +
    keys
      .map(
        (key) =>
          `${JSON.stringify(key)}:${stableJson(
            object[key],
          )}`,
      )
      .join(",") +
    "}"
  );
}

function createProgressSignature(
  state: {
    visitedUrls: string[];
    foundDocumentIds:
      string[];
    completedTasks:
      string[];
  },
): string {
  return createHash(
    "sha256",
  )
    .update(
      stableJson({
        visitedUrls:
          [...state.visitedUrls]
            .sort(),

        foundDocumentIds:
          [
            ...state
              .foundDocumentIds,
          ].sort(),

        completedTasks:
          [
            ...state
              .completedTasks,
          ].sort(),
      }),
    )
    .digest("hex");
}

let lastSignature:
  string | null = null;

let noProgressSteps = 0;

function recordProgress(
  signature: string,
): void {
  if (
    signature ===
    lastSignature
  ) {
    noProgressSteps += 1;
  } else {
    noProgressSteps = 0;
  }

  lastSignature =
    signature;

  if (
    noProgressSteps >= 3
  ) {
    throw new Error(
      "3ステップ連続で進捗がありません。",
    );
  }
}

もう少し調べます

追加情報を確認します

新しいURLを取得した
新しいドキュメントを取得した
テストが1件成功した
TODOが1件完了した
ファイルが変更された

進捗しましたか？

回答本文がある
参照したdocument_idが1件以上ある
追加ツール呼び出しがない

対象ファイルを変更済み
テストコマンドを実行済み
テスト成功
未処理TODOがない

import {
  z,
} from "zod";

const AgentResultSchema =
  z.object({
    status:
      z.enum([
        "completed",
        "blocked",
        "needs_user_input",
      ]),

    answer:
      z.string(),

    completedTasks:
      z.array(
        z.string(),
      ),

    remainingTasks:
      z.array(
        z.string(),
      ),
  });

{
  "status": "completed",
  "answer": "原因を特定しました。",
  "completedTasks": ["ログ確認", "設定確認"],
  "remainingTasks": []
}

function canFinish(
  result:
    z.infer<
      typeof AgentResultSchema
    >,
): boolean {
  return (
    result.status ===
      "completed" &&
    result.remainingTasks
      .length === 0
  );
}

if (
  response.toolCalls.length ===
    0
) {
  const final =
    validateFinalOutput(
      response,
    );

  if (final.ok) {
    return final.value;
  }
}

tool_choice = any

auto

残りステップは1です。
これ以上ツールを使用せず、
これまでの結果から最終回答を作成してください。

function getInstructions(
  step: number,
  maxSteps: number,
): string {
  const remaining =
    maxSteps - step;

  if (remaining <= 1) {
    return `
追加ツールは使用せず、
現在までの情報から
最終回答を作成してください。
    `.trim();
  }

  return `
必要な場合だけツールを使い、
十分な情報が集まったら
終了してください。
  `.trim();
}

Internal Server Error

if (
  reason ===
    "max_steps"
) {
  return {
    status:
      "partial",
    answer:
      createPartialAnswer(
        state,
      ),
  };
}

function createBudgetMessage(
  usedUsd: number,
  maxUsd: number,
): string {
  const remaining =
    Math.max(
      0,
      maxUsd -
        usedUsd,
    );

  return `
残り実行予算は
約$${remaining.toFixed(3)}です。

予算が少ない場合は
追加調査を止め、
現在までの結果をまとめてください。
  `.trim();
}

if (
  usedUsd >= maxUsd
) {
  throw new BudgetExceeded();
}

step 1～7: 通常実行

step 8: 終了を意識するよう通知

step 9: 新しい高コスト処理を制限

step 10: 強制停止

予癰70%: 通常実行

予癰80%: 残り予算を通知

予癰90%: 新規調査を抑制

予算100%: 強制終了

send_email
↓
send_email

type SendEmailInput = {
  operationId: string;
  to: string;
  subject: string;
  body: string;
};

const existing =
  await db.emailOperations
    .findUnique({
      where: {
        operationId:
          input.operationId,
      },
    });

if (existing) {
  return {
    status:
      "already_sent",
    messageId:
      existing.messageId,
  };
}

create_order

prepare_order
↓
confirm_order
↓
execute_order

親 Agent
↓
Research Agent
↓
Search Agent
↓
Research Agent
↓
親 Agent

type SharedBudget = {
  maxToolCalls: number;
  usedToolCalls: number;

  maxTokens: number;
  usedTokens: number;

  maxCostUsd: number;
  usedCostUsd: number;

  deadline: number;
};

function consumeToolCall(
  budget:
    SharedBudget,
): void {
  budget.usedToolCalls += 1;

  if (
    budget.usedToolCalls >
    budget.maxToolCalls
  ) {
    throw new Error(
      "グローバルTool予算を超えました。",
    );
  }
}

const MAX_SUBAGENTS = 3;

let subagentCount = 0;

function beforeSpawnSubagent():
  void {
  subagentCount += 1;

  if (
    subagentCount >
    MAX_SUBAGENTS
  ) {
    throw new Error(
      "Subagent数の上限に達しました。",
    );
  }
}

import {
  createToolFingerprint,
} from "./tool-fingerprint";

type AgentLimits = {
  maxSteps: number;
  maxToolCalls: number;
  maxTokens: number;
  maxCostUsd: number;
  maxDurationMs: number;
  maxDuplicateCalls: number;
};

class AgentBudgetGuard {
  private steps = 0;
  private toolCalls = 0;
  private tokens = 0;
  private costUsd = 0;

  private readonly startedAt =
    Date.now();

  private readonly duplicates =
    new Map<
      string,
      number
    >();

  constructor(
    private readonly limits:
      AgentLimits,
  ) {}

  beforeStep(): void {
    this.steps += 1;

    if (
      this.steps >
      this.limits.maxSteps
    ) {
      throw new Error(
        "max_steps",
      );
    }

    this.checkTime();
  }

  beforeTool(
    name: string,
    args: unknown,
  ): void {
    this.toolCalls += 1;

    if (
      this.toolCalls >
      this.limits
        .maxToolCalls
    ) {
      throw new Error(
        "max_tool_calls",
      );
    }

    const fingerprint =
      createToolFingerprint(
        name,
        args,
      );

    const duplicateCount =
      (
        this.duplicates.get(
          fingerprint,
        ) ?? 0
      ) + 1;

    this.duplicates.set(
      fingerprint,
      duplicateCount,
    );

    if (
      duplicateCount >
      this.limits
        .maxDuplicateCalls
    ) {
      throw new Error(
        "duplicate_tool_loop",
      );
    }

    this.checkTime();
  }

  recordUsage(
    usage: {
      totalTokens: number;
      costUsd: number;
    },
  ): void {
    this.tokens +=
      usage.totalTokens;

    this.costUsd +=
      usage.costUsd;

    if (
      this.tokens >
      this.limits.maxTokens
    ) {
      throw new Error(
        "max_tokens",
      );
    }

    if (
      this.costUsd >
      this.limits.maxCostUsd
    ) {
      throw new Error(
        "max_cost",
      );
    }
  }

  private checkTime():
    void {
    const elapsed =
      Date.now() -
      this.startedAt;

    if (
      elapsed >
      this.limits
        .maxDurationMs
    ) {
      throw new Error(
        "max_duration",
      );
    }
  }
}

const guard =
  new AgentBudgetGuard({
    maxSteps: 10,
    maxToolCalls: 20,
    maxTokens: 120_000,
    maxCostUsd: 0.50,
    maxDurationMs: 90_000,
    maxDuplicateCalls: 2,
  });

async function runAgent(
  initialInput: string,
): Promise<string> {
  const history:
    AgentMessage[] = [
      {
        role: "user",
        content:
          initialInput,
      },
    ];

  while (true) {
    guard.beforeStep();

    const response =
      await callModel(
        history,
      );

    guard.recordUsage({
      totalTokens:
        response.usage
          .totalTokens,

      costUsd:
        response.usage
          .estimatedCostUsd,
    });

    if (
      response.toolCalls
        .length === 0
    ) {
      return validateFinalAnswer(
        response.text,
      );
    }

    for (
      const call
      of response.toolCalls
    ) {
      guard.beforeTool(
        call.name,
        call.arguments,
      );

      const result =
        await executeToolWithTimeout(
          call,
        );

      history.push({
        role: "tool",
        toolCallId:
          call.id,
        content:
          JSON.stringify(
            result,
          ),
      });
    }
  }
}

agent_failed

type AgentStopReason =
  | "completed"
  | "max_steps"
  | "max_tool_calls"
  | "max_tokens"
  | "max_cost"
  | "max_duration"
  | "duplicate_tool_loop"
  | "no_progress"
  | "user_cancelled"
  | "tool_error";

CREATE TABLE ai_agent_runs (
  id BIGSERIAL PRIMARY KEY,

  trace_id UUID NOT NULL,

  agent_name
    VARCHAR(100)
    NOT NULL,

  status
    VARCHAR(32)
    NOT NULL,

  stop_reason
    VARCHAR(64)
    NOT NULL,

  steps
    INTEGER
    NOT NULL,

  tool_calls
    INTEGER
    NOT NULL,

  input_tokens
    BIGINT
    NOT NULL,

  output_tokens
    BIGINT
    NOT NULL,

  estimated_cost_usd
    NUMERIC(20, 12)
    NOT NULL,

  duration_ms
    INTEGER
    NOT NULL,

  created_at
    TIMESTAMPTZ
    NOT NULL
    DEFAULT NOW()
);

max_stepsが多い

duplicate_tool_loopが多い

max_costが増えた

特定ツールだけ繰り返している

const result =
  await run(
    agent,
    input,
    {
      maxTurns: 10,
    },
  );

const usage =
  result.state.usage;

console.log({
  requests:
    usage.requests,

  inputTokens:
    usage.inputTokens,

  outputTokens:
    usage.outputTokens,

  totalTokens:
    usage.totalTokens,
});

SELECT
  PERCENTILE_CONT(0.5)
    WITHIN GROUP (
      ORDER BY steps
    )
    AS p50_steps,

  PERCENTILE_CONT(0.95)
    WITHIN GROUP (
      ORDER BY steps
    )
    AS p95_steps,

  PERCENTILE_CONT(0.99)
    WITHIN GROUP (
      ORDER BY steps
    )
    AS p99_steps

FROM ai_agent_runs

WHERE
  created_at >=
    NOW()
    - INTERVAL '30 days';

SELECT
  COUNT(*) FILTER (
    WHERE
      stop_reason =
        'max_steps'
  )::NUMERIC
  /
  NULLIF(
    COUNT(*),
    0
  )
  AS max_steps_rate

FROM ai_agent_runs

WHERE
  created_at >=
    NOW()
    - INTERVAL '7 days';

本当にあと1ステップで完了したのか

同じ検索を繰り返していたのか

Tool Resultが分かりにくかったのか

終了条件が曖昧だったのか

{
  "status": "error"
}

{
  "ok": false,
  "code": "CUSTOMER_NOT_FOUND",
  "retryable": false,
  "message": "指定されたcustomer_idは存在しません。別のIDを取得してください。"
}

{
  "name": "search",
  "description": "Searches things"
}

{
  name:
    "search_documents",

  description: `
社内ドキュメントを
キーワード検索します。

同じqueryを繰り返しても
結果は変化しません。

必要な文書が見つからない場合は
別のqueryへ変更してください。
  `.trim()
}

search_web
google_search
internet_search
search_internet
web_lookup

get_profile

最初: get_profile / search_orders / create_report

プロフィール取得後: search_orders / create_report

注文取得後: create_report

needs_user_input

{
  "status": "needs_user_input",
  "answer": "対象の注文番号を入力してください。",
  "completedTasks": [],
  "remainingTasks": ["注文の確認"]
}

completed
needs_user_input
blocked

if (
  result.status ===
    "completed" ||
  result.status ===
    "needs_user_input" ||
  result.status ===
    "blocked"
) {
  return result;
}

ステップ

Tool Call

同一処理

Token

Cost

Time

モデル
↓
Tool Call
↓
Tool Result
↓
モデル

completed

needs_user_input
blocked

最大ステップ

最大Tool Call数

Toolごとの上限

同一Tool Callの重複上限

Token予算

料金予算

最大実行時間

進捗なし回数

明示的な完了条件

副作用の冪等性