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")

Aperta
#6,709 1 commento 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
25/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
python
Ambito
backend

Direzione di ricerca

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.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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 ---
Lingua principale
Python
Stelle
9.3k
Fork
1.5k
Merge medio
1g 5h
PR unite (30g)
520

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di MervinPraison/PraisonAI

Tutte le issue di MervinPraison/PraisonAI

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.