Docs describe APIs, routes and MCP methods the released packages do not have (session resume, long-poll delivery, MCP Tasks) and two examples that do not run

Aperta
#6,711 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à
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
45/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
python
Ambito
documentation

Direzione di ricerca

Start with the six named pages: guides/persistence/session-resume, features/gateway-durable-polling, mcp/mcp-tasks-api, features/gateway-inbound-hooks, features/gateway-durable-runs, and features/workflow-checkpoint-resume. Compare each claim and example with the released package APIs and the supplied reproduction script. Update the pages to match the released behavior or state which release provides each feature; rerun the checks and confirm the documented examples work.

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

Descrizione

bug claude documentation origin/outsider
Description

While testing PraisonAI's documented recovery features against the releases
current on 2026-09-29 (praisonaiagents 1.7.9, praisonai 4.7.11,
praisonai-bot 0.1.8, praisonai-mcp 0.1.10), we found these pages
describing things the packages do not have, or examples that do not run as
written. Each is checked by the script below, and each still holds on the
releases current on 2026-11-19 (praisonaiagents 1.8.0, praisonai 4.8.0,
praisonai-bot 0.2.0, praisonai-mcp 0.2.0) against the pages as they read
that day.

  1. Session resume (guides/persistence/session-resume): the page uses
    Session(session_id=..., persistence="sqlite", checkpoint_interval=...),
    Agent(name=..., session=session) and agent.resume(). Session.__init__
    has no persistence or checkpoint_interval, Agent has no session
    parameter, and there is no Agent.resume. (The working continuity,
    Agent(memory={"session_id": ...}), is on the other session-resume pages.)
  2. Long-poll delivery (features/gateway-durable-polling): the page
    documents POST /api/push/poll/ack (now with a note that it answers 503
    when no delivery manager is configured). With the page's push: block,
    it answers 404, as do /api/push/poll/register and /messages, while
    /health answers 200. gateway/push_polling.py defines the three routes,
    but gateway/server.py does not import it, so they are never mounted.
  3. MCP Tasks (mcp/mcp-tasks-api, "per MCP 2025-11-25"): the server
    answers tasks/get, tasks/result and tasks/cancel with -32601 Method not found, runs a tools/call carrying "task": {...} inline, and does
    not advertise tasks in its capabilities.
  4. Inbound hooks (features/gateway-inbound-hooks): the example calls
    gateway.register_agent("assistant", Agent(...)), but the signature is
    register_agent(agent, agent_id=None, *, overwrite=True). In our test
    (1.7.9; not re-run), every delivery to the example's hook then answered
    500 "agent not available". The same page gives the dedup store's default both ways ("By
    default the dedup store is in-memory" and "sqlite (default)").
  5. Gateway Quick Starts (features/gateway-durable-runs,
    features/gateway-durable-polling): the gateway.yaml examples have no
    channels: section, and start_with_config rejects them: "Missing
    required 'channels' section". Adding channels: {local: {}} (as in
    bots/local.py's docstring) makes them load.
  6. Workflow checkpoint resume (features/workflow-checkpoint-resume):
    from praisonaiagents import Agent, WorkflowManager fails in 1.8.0, as
    from praisonaiagents import WorkflowManager did in 1.7.9. In our test
    (1.7.9), execute() also needed the workflow's front-matter name, not the file
    name the example suggests.
Environment

Python SDK: praisonaiagents 1.8.0, praisonai 4.8.0, praisonai-bot 0.2.0, praisonai-mcp 0.2.0. No provider is called. Python 3.13 on Windows 11.

Reproduction

Re-checked on 2026-11-19 against praisonai 4.8.0, praisonaiagents 1.8.0, praisonai-bot 0.2.0 and praisonai-mcp 0.2.0, the current releases: same results. The output below is from those releases.

python repro.py (script below) after pip install praisonai==4.8.0 praisonai-bot==0.2.0 praisonai-mcp==0.2.0 websockets (the gateway needs
websockets, which a plain install of these three did not bring in). No API key and no model call;
nothing leaves 127.0.0.1. Output (the import error's path shortened):

praisonaiagents 1.8.0
praisonai 4.8.0
praisonai-bot 0.2.0
praisonai-mcp 0.2.0

1. guides/persistence/session-resume: Session(persistence=, checkpoint_interval=), Agent(session=), agent.resume()
   Session.__init__ parameters: ['self', 'session_id', 'user_id', 'agent_url', 'memory_config', 'knowledge_config', 'timeout', 'session_ttl']
   Agent(session=...) accepted: False
   Agent.resume exists: False

2. workflow-checkpoint-resume: from praisonaiagents import WorkflowManager
   ImportError: cannot import name 'WorkflowManager' from 'praisonaiagents' (.../site-packages/praisonaiagents/__init__.py)

3. gateway-inbound-hooks: gateway.register_agent("assistant", Agent(...))
   signature: (self, agent: "'Agent'", agent_id: 'Optional[str]' = None, *, overwrite: 'bool' = True) -> 'str'

4. mcp-tasks-api: tasks/get, tasks/result, tasks/cancel, and tools/call with a task field
   tools/call -> {"content": [{"type": "text", "text": "result for AI"}], "isError": false}
   tasks/get -> {"code": -32601, "message": "Method not found: tasks/get"}
   tasks/result -> {"code": -32601, "message": "Method not found: tasks/result"}
   tasks/cancel -> {"code": -32601, "message": "Method not found: tasks/cancel"}
   capabilities advertise tasks: False

5. gateway-durable-runs / gateway-durable-polling: a gateway.yaml with no channels: section
   start_with_config:   - Missing required 'channels' section

6. gateway-durable-polling: POST /api/push/poll/{register,messages,ack} (channels: added)
   GET /health -> 200
   POST /api/push/poll/register -> 404
   POST /api/push/poll/messages -> 404
   POST /api/push/poll/ack -> 404
Expected

The pages match the released API, or say which release the features ship in.

repro.py
# --- repro.py (verbatim) ---
"""PraisonAI: documented APIs, routes and protocol methods that the released packages
do not have, and two examples that do not run as written.

`pip install praisonai==4.7.11 praisonai-bot==0.1.8 praisonai-mcp==0.1.10` then
`python repro.py`. No API key, no model call; nothing leaves 127.0.0.1.
"""

import asyncio
import inspect
import json
import os
import subprocess
import sys
import tempfile
import time
import urllib.error
import urllib.request
from importlib.metadata import version

for pkg in ("praisonaiagents", "praisonai", "praisonai-bot", "praisonai-mcp"):
    print(f"{pkg} {version(pkg)}")

print("\n1. guides/persistence/session-resume: Session(persistence=, checkpoint_interval=), Agent(session=), agent.resume()")
from praisonaiagents import Agent, Session  # noqa: E402

params = list(inspect.signature(Session.__init__).parameters)
print("   Session.__init__ parameters:", params)
print("   Agent(session=...) accepted:", "session" in inspect.signature(Agent.__init__).parameters)
print("   Agent.resume exists:", hasattr(Agent, "resume"))

print("\n2. workflow-checkpoint-resume: from praisonaiagents import WorkflowManager")
try:
    from praisonaiagents import WorkflowManager  # noqa: F401
    print("   import ok")
except ImportError as exc:
    print(f"   ImportError: {exc}")

print("\n3. gateway-inbound-hooks: gateway.register_agent(\"assistant\", Agent(...))")
from praisonai.gateway import WebSocketGateway  # noqa: E402

print("   signature:", inspect.signature(WebSocketGateway.register_agent))

print("\n4. mcp-tasks-api: tasks/get, tasks/result, tasks/cancel, and tools/call with a task field")
from praisonai_mcp.mcp_server.registry import MCPToolRegistry  # noqa: E402
from praisonai_mcp.mcp_server.server import MCPServer  # noqa: E402


async def mcp_check() -> None:
    registry = MCPToolRegistry()
    registry.register(name="search", handler=lambda query: "result for " + query, description="Search",
                      input_schema={"type": "object", "properties": {"query": {"type": "string"}},
                                    "required": ["query"]})
    server = MCPServer(tool_registry=registry)
    task_id = "786512e2-9e0d-44bd-8f29-789f320fe840"
    for i, (method, p) in enumerate([
            ("initialize", {"protocolVersion": "2025-11-25", "capabilities": {},
                            "clientInfo": {"name": "check", "version": "0"}}),
            ("tools/call", {"name": "search", "arguments": {"query": "AI"}, "task": {"ttl": 60000}}),
            ("tasks/get", {"taskId": task_id}), ("tasks/result", {"taskId": task_id}),
            ("tasks/cancel", {"taskId": task_id})]):
        reply = await server.handle_message({"jsonrpc": "2.0", "id": i, "method": method, "params": p})
        if method != "initialize":
            print(f"   {method} -> {json.dumps(reply.get('result') or reply.get('error'))[:160]}")
    print("   capabilities advertise tasks:", "tasks" in server.get_capabilities())


asyncio.run(mcp_check())

print("\n5. gateway-durable-runs / gateway-durable-polling: a gateway.yaml with no channels: section")
tmp = tempfile.mkdtemp(prefix="praison-docs-check-")
env = dict(os.environ, USERPROFILE=tmp, HOME=tmp, GATEWAY_AUTH_TOKEN="local-check-token",
           OPENAI_API_KEY="placeholder-not-a-key")
yaml_head = "agents:\n  alerts:\n    instructions: \"Summarise incoming alert events in one sentence\"\n"
yaml_tail = ("gateway:\n  host: 127.0.0.1\n  port: 8984\npush:\n  enabled: true\n  polling:\n    enabled: true\n"
             "    long_poll_timeout: 30\n    max_batch_size: 100\n    max_queue_size: 1000\n")
with open(os.path.join(tmp, "no_channels.yaml"), "w", encoding="utf-8") as f:
    f.write(yaml_head + yaml_tail)
with open(os.path.join(tmp, "with_channels.yaml"), "w", encoding="utf-8") as f:
    f.write(yaml_head + "channels:\n  local: {}\n" + yaml_tail)
start = ("import asyncio, sys; from praisonai.gateway import WebSocketGateway; "
         "asyncio.run(WebSocketGateway().start_with_config(sys.argv[1]))")
p = subprocess.run([sys.executable, "-c", start, "no_channels.yaml"], cwd=tmp, env=env, capture_output=True,
                   text=True, timeout=120)
print("   start_with_config:", (p.stderr.strip().splitlines() or ["(no error)"])[-1][:160])

print("\n6. gateway-durable-polling: POST /api/push/poll/{register,messages,ack} (channels: added)")
gw = subprocess.Popen([sys.executable, "-c", start, "with_channels.yaml"], cwd=tmp, env=env,
                      stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, stdin=subprocess.DEVNULL)


def call(method: str, path: str):
    req = urllib.request.Request("http://127.0.0.1:8984" + path, data=b"{}" if method == "POST" else None,
                                 method=method, headers={"Authorization": "Bearer local-check-token",
                                                         "Content-Type": "application/json"})
    try:
        with urllib.request.urlopen(req, timeout=5) as r:
            return r.status
    except urllib.error.HTTPError as e:
        return e.code
    except Exception:  # noqa: BLE001
        return "no answer"


try:
    for _ in range(120):
        if gw.poll() is not None or call("GET", "/health") != "no answer":
            break
        time.sleep(0.5)
    print("   GET /health ->", call("GET", "/health"))
    for route in ("register", "messages", "ack"):
        print(f"   POST /api/push/poll/{route} ->", call("POST", "/api/push/poll/" + route))
finally:
    if os.name == "nt":
        subprocess.run(["taskkill", "/T", "/F", "/PID", str(gw.pid)], capture_output=True)
    else:
        gw.kill()
# --- 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.