Core SDK: async @tool returns a coroutine repr and BaseTool/aliased tools are never advertised, shared-agent async tasks leak prompts and Workflow.astart ignores cancel, emergency truncation orphans tool results and session-scoped recall misses stored memories
メンテナーはふだん 1 日以内に返信
まだ誰も着手していません。
評価
調査の方向性
Start with the named entry points: execution_mixin.py and chat_mixin.py for tool handling, agents.py and workflows.py for async orchestration, and context/manager.py for truncation; inspect the cited sibling fixes and existing tests. Reproduce each finding with the mocked LLM or direct calls described in the issue, then verify async tools, shared-agent isolation, cancellation, tool-result pairing, and session-scoped memory recall.
索引モデルが issue の本文から書いたものです。
説明
Summary
This audit covered src/praisonai-agents/praisonaiagents, mainly the tool layer, multi-agent orchestration, and context/memory. It found three gaps that break the SDK's own contracts at runtime without raising an error. Each one has a working sibling path in the same codebase that already does the right thing, so every fix reuses existing code (DRY) instead of adding new API surface.
| # | Gap | Contract broken | Severity |
|---|---|---|---|
| 1 | The Agent does not use the tool protocol (BaseTool / FunctionTool) |
Async @tool returns a coroutine repr under achat(). BaseTool subclasses and @tool(name=...) are never sent to the LLM |
High |
| 2 | Async orchestration is neither isolated nor cancellable | AgentTeam async_execution=True tasks that share an Agent read each other's prompts. Cancelling Workflow.astart() does not stop the run |
High |
| 3 | Recovery and recall paths lose state integrity | emergency_truncate leaves orphan role="tool" messages on the overflow-recovery path. Memories stored through the public store_memory / astore_memory are never recalled when session_id is set |
High |
Every finding below was reproduced against main @ 0e2d976 with no API keys, using a mocked LLM or direct internal calls. The observed output is quoted.
None of these duplicates an open or closed issue. The nearest are #6202 (orphans from tool-call budget truncation, fixed), #6217 (compaction desyncs the save index, fixed), #6266 (cancelling a Parallel step or an AgentTeam, fixed) and #5786 (multi-term async prefetch). Those fixes did not reach the code paths described here.
Gap 1: the Agent does not use the tool protocol it defines
tools/base.py (BaseTool) and tools/decorator.py (@tool → FunctionTool) are the documented extension points. The Agent's tool path ignores both: it advertises tools by looking up __name__, and it dispatches through a sync .run() wrapper.
1a. An async @tool is never awaited under achat() / astart() / async workflows
agent/execution_mixin.py:2046 and :2093:
call_target = func.run if isinstance(func, BaseTool) else func
...
if inspect.iscoroutinefunction(call_target): # False: FunctionTool.run is sync
...
else:
result = await _run_sync(...) # returns an un-awaited coroutine
tools/decorator.py:214:
def run(self, **kwargs) -> Any:
kwargs = inject_state_into_kwargs(kwargs, self._injected_params)
return self._func(**kwargs) # coroutine object when _func is async
Repro
import asyncio
from praisonaiagents import Agent, tool
@tool
async def adeco(x: int) -> str:
"""async tool"""
return f"adeco:{x}"
a = Agent(name="t", instructions="x", tools=[adeco])
print(repr(asyncio.run(a.execute_tool_async("adeco", {"x": 5}))))
print(repr(a.execute_tool("adeco", {"x": 5})))
Observed
RuntimeWarning: coroutine 'adeco' was never awaited
{'result': '<coroutine object adeco at 0x7f23366c7040>'} # async path → garbage to the LLM
'adeco:5' # sync path is correct
With a fake LLM driving a full achat(), the tool message the model receives is {"result": "<coroutine object adeco ...>"}.
Impact: async @tools silently do nothing under every async entry point. This covers HTTP, database and MCP-style I/O, which are exactly the tools people write as async. The model is shown a repr string and usually reports success. The tool timeout has no effect, because the body never runs.
1b. BaseTool subclasses and @tool(name=...) aliases are never advertised to the LLM
agent/chat_mixin.py:1407-1408:
elif getattr(tool, "name", None) and hasattr(tool, "run"):
tool_def = self._generate_tool_definition(tool.name) # looks the tool up by name
agent/agent.py:582-585:
for tool in self.tools:
if callable(tool) and getattr(tool, '__name__', '') == function_name:
A BaseTool instance has no __name__. @tool(name="search_web") def sw has __name__ == "sw". Neither matches, so the tool's own get_schema() is never consulted. That also means @tool(description=...) and dynamic_schema_overrides are dropped even when the name does match.
Repro
from praisonaiagents import Agent, tool
from praisonaiagents.tools.base import BaseTool
@tool(name="search_web")
def sw(q: str) -> str:
"""search"""
return "q:" + q
class Weather(BaseTool):
name = "weather"; description = "weather tool"
def run(self, city: str) -> str: return "sunny " + city
a = Agent(name="t", instructions="x", tools=[sw, Weather()])
print([t["function"]["name"] for t in a._format_tools_for_completion()])
print(a.execute_tool("search_web", {"q": "2"}))
Observed
Could not generate definition for tool: search_web
Could not generate definition for tool: weather
[] # the model is shown no tools
q:2 # yet dispatch by that name works
Impact: the documented class-based extension point (tools/base.py) and the name= alias cannot be used with Agent, sync or async. The only signal is a log warning.
Proposed fix (one resolver, reused by both paths)
# tools/base.py (or a small helper next to it)
def tool_callable(func):
"""Return (call_target, is_async) for any tool: plain function, FunctionTool or BaseTool."""
target = func.run if isinstance(func, BaseTool) else func
raw = getattr(func, "_func", target)
return target, inspect.iscoroutinefunction(target) or inspect.iscoroutinefunction(raw)
# agent/execution_mixin.py ~2093
call_target, is_async = tool_callable(func)
if is_async:
res = call_target(**call_arguments)
result = await res if inspect.isawaitable(res) else res
else:
result = await _run_sync(...)
if inspect.isawaitable(result): # defensive: never ship a coroutine to the LLM
result = await result
# agent/chat_mixin.py ~1407: trust the tool's own schema before any name lookup
elif isinstance(tool, BaseTool):
formatted_tools.append(fix_array_schemas_in_def(tool.get_schema()))
# agent/agent.py ~583: match the advertised name as well as __name__
if callable(tool) and function_name in (getattr(tool, "name", None), getattr(tool, "__name__", None)):
Tests: an async @tool through achat() with a mocked LLM, and both BaseTool() and @tool(name=...) appearing in _format_tools_for_completion() with their description.
Gap 2: async orchestration is neither isolated nor cancellable
2a. AgentTeam async_execution=True tasks that share one Agent read each other's prompts
agents/agents.py:2102 / :2147 queue self.arun_task(task_id) coroutines. These run under asyncio.gather (_gather_with_isolation, :1941). Each one then calls (:1577):
agent_output = await _execute_with_agent_async(
context.executor_agent, context.task_prompt, context.task, context.tools, stream=self.stream)
All of them use the same executor_agent, and so the same chat_history. The Workflow engine already fixed this exact problem (workflows/workflows.py:246):
def _branch_agent(agent):
"""... One Agent instance appends every call to its own chat_history, so
running it from several threads at once leaks sibling prompts into each
request. The fork shares config, tools and memory but owns its history."""
AgentTeam never calls it.
Repro (one Agent, two async_execution=True tasks, team.astart(); _achat_completion_with_retry patched to record the messages sent):
B user msgs sent to LLM: 1
You need to do the following task: TOPIC_BETA. ...
A user msgs sent to LLM: 2
You need to do the following task: TOPIC_BETA. ... <- sibling's prompt leaked in
You need to do the following task: TOPIC_ALPHA. ...
Impact: the most common parallel pattern, one researcher agent over N async tasks, produces outputs that mix topics and depend on timing, and it pays for the extra tokens. The tasks are not independent.
2b. Cancelling Workflow.astart() / arun() does not stop the run
workflows/workflows.py:2638-2641:
result = await loop.run_in_executor(
None,
copy_context_to_callable(lambda: self.run(input, llm, verbose))
)
Cancelling the awaiting task only detaches the caller. The executor thread keeps running every remaining step. AgentTeam.arun_all_tasks (#6266) and the Workflow's own Parallel block already use _stop_scope(); astart / arun do not.
Repro (5 function steps of 0.2 s each; the task is cancelled at 0.3 s):
0.20s step 0 executed (side effect)
0.30s caller: astart cancelled
0.40s step 1 executed (side effect)
0.60s step 2 executed (side effect)
0.80s step 3 executed (side effect)
1.00s step 4 executed (side effect)
steps run after cancel: [0, 1, 2, 3, 4] wf.status= completed
Impact: asyncio.wait_for timeouts, server request cancellation and user aborts cannot stop a workflow. LLM and tool calls, with their side effects and cost, keep running with nobody waiting, and the run reports status="completed".
Proposed fix (reuse the existing primitives)
# agents/agents.py, when building an async batch
from ..workflows.workflows import _enter_branch, _branch_agent, _BRANCH_AGENTS
shared = _agents_used_more_than_once(batch) # id(agent) seen >1 in this batch
token = _enter_branch(shared)
try:
await self._gather_with_isolation([c for _, c in batch])
finally:
_BRANCH_AGENTS.reset(token)
# and in aexecute_task: executor = _branch_agent(context.executor_agent)
# (move _branch_agent / _enter_branch to a neutral module, e.g. agent/_branching.py, to avoid an agents→workflows import)
# workflows/workflows.py astart/arun
from ..agent.chat_mixin import _stop_scope
with _stop_scope(): # sets the stop event on exit/cancel
try:
return await loop.run_in_executor(None, copy_context_to_callable(lambda: self.run(input, llm, verbose)))
except asyncio.CancelledError:
self.status = "cancelled"
raise
# plus: check the active stop event at the top of each step in _run_impl and in Loop/Repeat iterations
Tests: two async tasks on one agent each send exactly one task prompt, and a cancelled astart() runs no step that starts after the cancel and ends with status == "cancelled".
Gap 3: recovery and recall paths lose state integrity
3a. ContextManager.emergency_truncate leaves orphan role="tool" messages, on the overflow-recovery path itself
context/manager.py:863-886 keeps the newest messages that fit and breaks at the first one that does not. Only user messages get a partial keep. When the cut falls on the assistant tool_calls message, its tool results are kept without it:
for msg in reversed(other_msgs):
msg_tokens = estimate_message_tokens(msg)
if tokens_used + msg_tokens <= remaining_budget:
kept_msgs.insert(0, msg)
...
else:
if msg.get("role") == "user" ...: # only user msgs are partially kept
...
break
result.extend(kept_msgs) # may start with role="tool"
Every other trimming path already guards against this with context/optimizer.py:18 _skip_leading_tool_messages (Issue #3089) or the compactor's pair handling. This one does not, and it is the path used when things are already failing:
agent/chat_mixin.py:2491:_shrink_after_context_overflow, the retry after the provider rejected the request as too longagent/chat_mixin.py:2505:_fit_overflow_ceiling, every later turnagent/chat_mixin.py:3770/:3796: the hard-limit (>95%) path and the fallback when context management fails
Repro
from praisonaiagents.context.manager import ContextManager
msgs = [{'role':'system','content':'sys'},
{'role':'user','content':'Q1 '+'x'*4000},
{'role':'assistant','content':'calling '+'y'*2000,
'tool_calls':[{'id':'c1','type':'function','function':{'name':'f','arguments':'{}'}}]},
{'role':'tool','tool_call_id':'c1','content':'r'*400},
{'role':'assistant','content':'done'}]
r = ContextManager(model='gpt-4o-mini').emergency_truncate(msgs, 200)
print([(m['role'], m.get('tool_call_id'), 'tool_calls' in m) for m in r])
Observed
[('system', None, False), ('tool', 'c1', False), ('assistant', None, False)]
Impact: a long tool-using session hits overflow, and the recovery retry then sends an invalid transcript. OpenAI and Anthropic return 400 for this, so the session cannot recover. Because _overflow_ceilings remembers the limit, every later turn repeats the failure.
3b. Memories stored through the public API are never recalled when session_id is configured
Recall always filters on session_id (agent/async_memory_mixin.py:96-100, and the same in the sync and async turn-start prefetch, chat_mixin.py:360-371 / :565):
if session_id:
scoped_kwargs["session_id"] = session_id
metadata_filter = dict(scoped_kwargs.get("metadata_filter") or {})
metadata_filter["session_id"] = session_id
Only the internal _persist_memory_turn (agent/memory_mixin.py:1103-1109) stamps session_id into the record metadata. Its own comment warns that "a turn missing either key is silently dropped on recall". The public Agent.store_memory (agent/agent.py:5502) and astore_memory (agent/async_memory_mixin.py:49-61) pass metadata through without stamping it.
Repro
import asyncio
from praisonaiagents import Agent
from praisonaiagents.config import MemoryConfig
a = Agent(name="m", instructions="x",
memory=MemoryConfig(backend="sqlite", user_id="alice", session_id="s1"))
a.store_memory("my codename is ORANGE-PANDA", memory_type="short_term")
print("async search:", asyncio.run(a.asearch_memory("codename")))
print("unscoped:", [r.get("text", r.get("content"))
for r in a._memory_instance.search_short_term("codename", user_id="alice")])
Observed
async search: []
unscoped: ['my codename is ORANGE-PANDA'] # the row exists but has no session_id
Impact: facts a developer stores explicitly, the main use of store_memory, are never recalled in any agent that has a session. No error is raised. Multi-tenant apps, which are exactly the ones setting session_id, are the ones affected.
Proposed fix (one shared helper for each)
# context/manager.py emergency_truncate, before result.extend(kept_msgs)
from .optimizer import _skip_leading_tool_messages
kept_msgs = _skip_leading_tool_messages(kept_msgs)
# agent/memory_mixin.py: a single scope stamper used by every write path
def _stamp_memory_scope(self, metadata):
cfg, md = getattr(self, "_memory_config", None), dict(metadata or {})
for key in ("user_id", "session_id"):
val = getattr(cfg, key, None)
if val:
md.setdefault(key, val)
return md
# store_memory / astore_memory / _persist_memory_turn:
# kwargs["metadata"] = self._stamp_memory_scope(kwargs.get("metadata"))
Tests: an emergency_truncate cut that falls immediately after an assistant tool_calls message never returns a leading tool message, and store_memory → search_memory / asearch_memory round-trips with session_id set, both sync and async.
Also observed (lower priority, not in the top 3)
- On a resumed session with
auto_save, the new turn is written twice.memory_mixin.py:667prepends the restored history but does not move_auto_save_last_indexforward. - Under
process="workflow", the upstream output appears three times in the downstream prompt when a task uses bothnext_tasksandcontext.process/process.py:811andagents/agents.py:536both inject it. - PEP 604 unions (
int | None,list[str] | None) are advertised as"string".tools/schema.py:57checks onlytyping.Union, while the coercer atagent/tool_execution.py:132already handlestypes.UnionType.
Alignment with the design principles
- Protocol-driven: Gap 1 makes the Agent honour
BaseTool.get_schema()andFunctionToolinstead of going around them. - Multi-agent and async safe by default: Gap 2 extends the existing
_branch_agentand_stop_scopeprimitives to the two paths that missed them. - DRY and no new API: every fix reuses a helper that already exists (
_skip_leading_tool_messages,_branch_agent,_stop_scope, the scope stamping in_persist_memory_turn). No new params, modules or exports. - No hot-path cost: each fix is an
isinstancecheck, anif, or a fork that happens only when one agent is shared inside a concurrent batch.
🤖 Generated with Claude Code
- 主要言語
- Python
- スター
- 9.3k
- フォーク
- 1.5k
- 平均マージ
- 1日 5時間
- マージ済み PR(30日)
- 520
環境構築
このプロジェクトには開発コンテナ、Dockerfile、コントリビューションガイドがありません。まず README を読み、一般的な手順ははじめてのコントリビューションガイドを参照してください。
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
MervinPraison/PraisonAI のほかの issue
-
難易度 2/5 1〜3時間 初心者へのやさしさ 82/100
MervinPraison/PraisonAI#6710 · コメント 1 件 ·
メンテナーはふだん 1 日以内に返信
-
claude
難易度 2/5 1〜3時間 初心者へのやさしさ 74/100
MervinPraison/PraisonAI#6707 ·
メンテナーはふだん 1 日以内に返信
-
bug claude
難易度 1/5 1時間未満 初心者へのやさしさ 90/100
MervinPraison/PraisonAI#6671 ·
メンテナーはふだん 1 日以内に返信
-
Compaction budget regression fixture remains below budget with accurate tokenization再び着手できるかも このイシューのプルリクエストはマージされずにクローズされました。 オープン
難易度 2/5 1〜3時間 初心者へのやさしさ 62/100
MervinPraison/PraisonAI#5418 · コメント 3 件 ·
メンテナーはふだん 1 日以内に返信
-
bug claude documentation
難易度 2/5 1〜3時間 初心者へのやさしさ 70/100
MervinPraison/PraisonAI#5341 · コメント 3 件 ·
メンテナーはふだん 1 日以内に返信
MervinPraison/PraisonAI の issue をすべて見る
似ている issue
-
cognition
難易度 2/5 1〜3時間 初心者へのやさしさ 82/100
メンテナーはふだん 1 日以内に返信
-
難易度 1/5 1時間未満 初心者へのやさしさ 78/100
collabnix/awesome-mcp-lists#433 ·
メンテナーはふだん 4 日以内に返信
-
CrossEntropyFilter raises on zero probabilities and single-class results対応中かも @NopeCharon が今日担当しました。 オープン
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
メンテナーはふだん 1 日以内に返信
-
bug
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
datajoint/datajoint-python#1703 ·
メンテナーはふだん 6 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
Archmonger/ServeStatic#129 ·