Tools get no key that stays stable across PraisonAI's own repeat paths (idempotency_key is empty outside durable runs; state.run_id is "unknown")

オープン
#6,709 コメント 1 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
5/5
見積もり時間
1週間以上
初心者へのやさしさ
25/100
issue の種類
機能追加
明瞭さ
おおむね明確
活発さ
活発
技術スタック
python
領域
backend

調査の方向性

Start with the documented idempotency_key and injected state behavior, then trace tool execution, task retries, checkpoint resume, gateway delivery, and approval journaling. The issue provides a reproduction script, but making keys stable across retries that ask the model again requires deciding how to match repeated calls. Done means tools can distinguish new calls from framework repeats across the listed paths, with behavior and documentation verified for each.

索引モデルが issue の本文から書いたものです。

説明

bug claude documentation origin/outsider
Description

Context: a private report on PraisonAI's default tool retry re-running a tool that had already committed was closed as expected behaviour. Taking that as the design, this issue is about what a tool needs in order to cope with it: a key that stays the same across PraisonAI's own repeats.

A tool with an irreversible effect (a payment, an email) needs a key that is
the same when PraisonAI repeats the call and different for a genuinely new
call, so it can pass it to its provider as an idempotency key. The docs offer
two:

  • durable-tool-runs: "Any tool whose signature accepts idempotency_key (or
    **kwargs) automatically receives a stable per-call key on every
    invocation";
  • injected-state: state.run_id, "Unique ID for this run".

Outside a durable run the first is an empty string and the second is the
None (with state.session_id "default"), in every run. So a
tool has nothing that separates one run's payment from the next run's:

praisonaiagents 1.8.0
default  run 1: the tool saw [{'idempotency_key': '', 'state.run_id': None, 'state.session_id': 'default'}]
default  run 2: the tool saw [{'idempotency_key': '', 'state.run_id': None, 'state.session_id': 'default'}]
durable  run 1: the tool saw [{'idempotency_key': 'e4a7029f-2137-46f4-9b35-7855838590be:0:pay_invoice', 'state.run_id': None, 'state.session_id': 'default'}]
durable  run 2: the tool saw [{'idempotency_key': 'ed954752-7afa-4a2c-b552-0dfb394b471c:0:pay_invoice', 'state.run_id': None, 'state.session_id': 'default'}]

(Registry warnings trimmed; script below.)

In a durable run the key works as documented: our tests with a provider that
honours it stopped the repeat after a crash-and-resume and kept every
legitimate payment. The key is built from the durable run and the call's
sequence number in it, though, and several of PraisonAI's documented repeat
paths either start a new run or give the repeated call a new sequence
number. In our test harness (praisonaiagents 1.7.9; not re-run on 1.8.0, and not in the script below) each of these re-ran a
committed payment, and the tool saw a different key, or none, on the repeat:

Path What repeats Key on the repeat
Task retry (max_retries, default 3) the whole task, from its prompt none by default; a new key in durable mode (the same durable run, but the retried call gets the next sequence number: …:0:pay_invoice, then …:1:pay_invoice)
Team checkpoint resume ("in-flight work continues, no re-runs") the task in flight at the crash none by default; a new key in durable mode
Workflow checkpoint resume ("without re-running steps that already finished") the step in flight at the crash none by default; a new key in durable mode
Gateway durable runs (the page now says the gateway "does not auto-resume on restart") a client's resend after the restart, which starts a new run a new key (durable is on by default here)
Durable approvals the in-flight approved call, after a new approval prompt the same key (durable), but the approver is asked again: KIND_APPROVAL is defined in runtime/journal.py and never written, although the page says "approval decisions are journalled as KIND_APPROVAL events"

The framework does hold ids near the tool, but on most of these paths none
of them would work as the key on its own:

  • The model's tool-call id (passed to execute_tool as tool_call_id)
    stays the same when the tool itself is retried, and differs between two
    calls. It would stop the default tool retry's duplicate. It does not
    survive the paths above: each one asks the model again, and the model
    issues a new call id.
  • The approval backend's approval_id is minted per request, so the
    re-opened approval has a new one.
  • The gateway hook's message_id is one per delivery. It stays the same
    across a redelivery, but two payments requested in one delivery share it.
    It is a scope for a key, not a key by itself.
  • The hierarchical loop's task id covers the whole task, so it cannot tell
    apart two payments made in one task.

A key that survives a repeat which re-runs the model has to be carried over
from the first attempt, not read from the new one.

Environment

Python SDK, praisonaiagents 1.8.0. Provider: OpenAI-compatible, played by a local fake endpoint (no API key). Python 3.13 on Windows 11.

Reproduction

Re-checked on 2026-11-19 against praisonaiagents 1.8.0, the current release: the same result, except that state.run_id is now None where 1.7.9 gave "unknown". The output above is from 1.8.0.

Self-contained script below (pip install praisonaiagents==1.8.0, then
python repro.py). No API key; nothing leaves 127.0.0.1. A local fake OpenAI
endpoint asks for one pay_invoice call per run; the tool is a @tool
declaring idempotency_key and state: Injected[AgentState].

Suggestions
  • Fill state.run_id and state.session_id as injected-state documents,
    or document that they are placeholders outside certain modes.
  • Pass a per-call key to any tool that declares idempotency_key, not only
    in durable runs. Outside a durable run, the model's tool-call id is enough
    for the default tool retry, which does not ask the model again.
  • Keep the documented key the same across the framework's own repeats:
    carry the durable run across the ones that start a new run (team restore,
    workflow restore, gateway restart). Task retry keeps the run but numbers
    the retried call afresh, so it also needs the first attempt's key to be
    reused. These repeats ask the model again, so no id read from the new
    attempt can serve as the key, and matching a retried call to the call it
    repeats is a design decision we have not tested. For gateway deliveries,
    the hook's message_id can scope the key but cannot replace it.
  • Docs: until then, qualify the team and workflow pages' "no
    re-runs" wording for the task or step in flight at a crash, and the durable
    approvals page's KIND_APPROVAL sentence.
repro.py
# --- repro.py (verbatim) ---
"""PraisonAI: what a tool receives to key an irreversible call on, with and without
durable execution.

`pip install praisonaiagents==1.7.9` then `python repro.py`. No API key; nothing leaves
127.0.0.1. A local fake OpenAI endpoint asks for one pay_invoice call per run. The tool
is a `@tool` declaring the documented `idempotency_key` parameter and
`state: Injected[AgentState]`.
Two separate runs are made in each mode. Nothing in PraisonAI is patched.
"""

import json
import os
import tempfile
import threading
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

SEEN = []


class FakeOpenAI(BaseHTTPRequestHandler):
    def do_POST(self):  # noqa: N802
        body = json.loads(self.rfile.read(int(self.headers["Content-Length"])))
        done = any(m.get("role") == "tool" for m in body["messages"])
        call = {"id": "call_1", "type": "function", "function": {
            "name": "pay_invoice",
            "arguments": json.dumps({"invoice": "INV-1001", "payee": "ACME-SUPPLIES", "amount": "250.00"})}}
        message = {"role": "assistant", "content": "Paid."} if done else \
            {"role": "assistant", "content": None, "tool_calls": [call]}
        data = json.dumps({"id": "x", "object": "chat.completion", "created": 0, "model": "gpt-4o-mini",
                           "choices": [{"index": 0, "message": message,
                                        "finish_reason": "stop" if done else "tool_calls"}],
                           "usage": {"prompt_tokens": 1, "completion_tokens": 1, "total_tokens": 2}}).encode()
        self.send_response(200)
        self.send_header("Content-Type", "application/json")
        self.send_header("Content-Length", str(len(data)))
        self.end_headers()
        self.wfile.write(data)

    def log_message(self, *args):
        pass


server = ThreadingHTTPServer(("127.0.0.1", 8983), FakeOpenAI)
server.daemon_threads = True
threading.Thread(target=server.serve_forever, daemon=True).start()
os.environ.update(OPENAI_API_KEY="placeholder-not-a-key", OPENAI_BASE_URL="http://127.0.0.1:8983/v1")

from importlib.metadata import version  # noqa: E402

from praisonaiagents import Agent, ExecutionConfig, tool  # noqa: E402
from praisonaiagents.tools import Injected  # noqa: E402
from praisonaiagents.tools.injected import AgentState  # noqa: E402


def pay_invoice(invoice: str, payee: str, amount: str, idempotency_key: str = "",
                state: Injected[AgentState] = None) -> str:
    """Pay a vendor invoice. This moves money and cannot be undone.

    Args:
        invoice: Invoice number
        payee: Payee account
        amount: Amount to pay
    """
    SEEN.append({"idempotency_key": idempotency_key, "state.run_id": getattr(state, "run_id", None),
                 "state.session_id": getattr(state, "session_id", None)})
    return '{"status": "PAID"}'


print(f"praisonaiagents {version('praisonaiagents')}", flush=True)
with tempfile.TemporaryDirectory(ignore_cleanup_errors=True) as tmp:
    for mode in ("default", "durable"):
        for run in (1, 2):
            SEEN.clear()
            kwargs = {"execution": ExecutionConfig(durable=True, journal_path=os.path.join(tmp, "journal.db"))} \
                if mode == "durable" else {}
            Agent(name="payer", instructions="You pay vendor invoices.", tools=[tool(pay_invoice)], llm="gpt-4o-mini",
                  **kwargs).start("Pay invoice INV-1001 to ACME-SUPPLIES for 250.00.")
            print(f"{mode:8} run {run}: the tool saw {SEEN}", flush=True)
# --- end repro.py ---
主要言語
Python
スター
9.3k
フォーク
1.5k
平均マージ
1日 5時間
マージ済み PR(30日)
520

環境構築

このプロジェクトには開発コンテナ、Dockerfile、コントリビューションガイドがありません。まず README を読み、一般的な手順ははじめてのコントリビューションガイドを参照してください。

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

MervinPraison/PraisonAI のほかの issue

MervinPraison/PraisonAI の issue をすべて見る

似ている issue

Python の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。