agentx-dev 3.0.3__tar.gz → 3.0.5__tar.gz

{agentx_dev-3.0.3/agentx_dev.egg-info → agentx_dev-3.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentx-dev
-Version: 3.0.3
+Version: 3.0.5
 Summary: A lightweight LLM agent framework with multi-agent orchestration (Supervisor + dynamic specialist spawning), permission-gated default tools, MCP integration, and prompt-template presets.
 Author-email: Bruce-Arhin Shadrach <brucearhin098@gmail.com>
 License: MIT License

{agentx_dev-3.0.3 → agentx_dev-3.0.5}/agentx_dev/Runner/AgentRun.py

@@ -1047,6 +1047,7 @@ class AgentRunner:
         permissions: Any = None,
         include_denied_tools: bool = False,
         system_addendum: Optional[str] = None,
+        strict_tool_dispatch: bool = False,
     ):
         # PEP 8 alias: prefer lowercase `agent=`. Either argument works; passing
         # both raises so misuse is loud rather than silently ambiguous.
@@ -1132,6 +1133,16 @@ class AgentRunner:
         else:
             self.system_addendum = system_addendum
 
+        # When True: on unknown-tool dispatch, feed the model an error
+        # observation ("that tool doesn't exist; use one of [X,Y] or
+        # Final_Answer") and let the loop iterate rather than
+        # immediately falling to implicit-final. Only applies when the
+        # unknown action looks like a tool identifier (no spaces) —
+        # natural-language actions still go straight to implicit-final
+        # since retrying makes no sense there. Default False keeps
+        # the 3.0.4 behavior.
+        self.strict_tool_dispatch = strict_tool_dispatch
+
         self.auto_cache = auto_cache and config.caching_enabled
         self.auto_memory = auto_memory and config.memory_enabled
         _setup = _ensure_auto_setup() if (self.auto_cache or self.auto_memory) else None
@@ -1361,53 +1372,28 @@ class AgentRunner:
                 yield {"type": "final", "content": final_answer}
                 break
 
-            # Guardrail: the model emitted an `action` value that is
-            # neither a terminal-answer variant NOR a registered tool.
-            # Two scenarios trigger this:
-            #   1. use_function_calling=True: the parser tool schema
-            #      accepts any string, so the model stuffs its natural-
-            #      language closing text into `action` (e.g. "Provide a
-            #      response to the athlete."). Without this guard, the
-            #      runner would dispatch it as a tool, get "not found",
-            #      and the turn dies.
-            #   2. action="" (empty). Under FC, the model sometimes
-            #      omits `action` entirely; Pydantic falls back to the
-            #      field default. Same failure — empty tool name.
-            # Route both to Final_Answer, built from whatever text the
-            # model actually provided (thought + action + action_input).
-            known_tools = set(self.func) | set(self.args)
-            if not action or action not in known_tools:
-                parts: List[str] = []
-                if thought:
-                    parts.append(str(thought))
-                # Only include `action` in the reply if it looks like
-                # real response text (not empty, not a suspicious short
-                # sentinel like "answer"). Skip empty.
-                if action and action.strip():
-                    parts.append(str(action))
-                if action_input and str(action_input).strip():
-                    parts.append(str(action_input))
-                final_answer = "\n\n".join(parts) or (
-                    "(agent emitted an unrecognized action and no text)"
-                )
+            # Normalize BEFORE the known-tools check — OpenAI's FC path
+            # sometimes returns tool names with a "functions." prefix
+            # ("functions.get_my_scores" instead of "get_my_scores").
+            # Without this, a valid tool call falls through to the
+            # implicit-final guardrail, which then leaks the model's
+            # internal Thought into user-visible text. Rewrite `action`
+            # here so the rest of the loop uses the canonical name.
+            normalized_action = self.registry._normalize_tool_name(action)
+            if normalized_action != action:
                 if self.verbose:
-                    preview = (action or "<empty>")[:60]
                     print(
-                        f"\x1B[1;33m[loop] implicit-final: action "
-                        f"'{preview}' is not a registered tool and not "
-                        f"a Final_Answer variant; treating turn as "
-                        f"Final_Answer\x1B[0m"
+                        f"\x1B[3;33m[loop] normalized action "
+                        f"'{action}' -> '{normalized_action}'\x1B[0m"
                     )
-                yield {"type": "final", "content": final_answer}
-                break
-
-            # Loop-level spiral check — same (action, args) as the last
-            # turn? Count it. Three in a row and we bail with a synthesized
-            # Final_Answer built from whatever real data was gathered
-            # before the spiral. Catches BOTH the "refused" spiral and
-            # the "tool not found" spiral (gpt-4o-mini did both in
-            # traces). Cheaper than dispatch — we abort before the tool
-            # even runs on the 3rd repeat.
+                action = normalized_action
+
+            # Loop-level spiral check — 3 identical (action, args) in a
+            # row and we bail. Placed BEFORE the known-tools branch so
+            # it catches BOTH kinds of spiral: a valid tool getting
+            # re-dispatched (dup-guard also catches this at the tool
+            # layer), and an unknown tool being retried via strict-mode
+            # (dup-guard would never see those since dispatch skips them).
             try:
                 action_sig = f"{action}::{json.dumps(action_input, sort_keys=True, default=repr)}"
             except Exception:
@@ -1442,6 +1428,102 @@ class AgentRunner:
                 yield {"type": "final", "content": final_answer}
                 break
 
+            # Guardrail: the model emitted an `action` value that is
+            # neither a terminal-answer variant NOR a registered tool
+            # (even after normalization). Two scenarios trigger this:
+            #   1. use_function_calling=True + missing schema guidance:
+            #      the model stuffs its natural-language response text
+            #      into `action` (e.g. "Provide a response to the
+            #      athlete."). Route to final so the loop terminates.
+            #   2. action="" (missing field, Pydantic default).
+            # NEVER include `Thought` in the user-facing final — the
+            # Thought is internal reasoning ("The user needs their
+            # scores; I'll fetch them") and leaking it to the user
+            # exposes the agent's introspection. Prefer action_input
+            # (that's what the model wanted the user to see). Only fall
+            # back to `action` when action_input is empty AND action
+            # looks like natural-language text (contains a space, not
+            # just an identifier).
+            known_tools = set(self.func) | set(self.args)
+            if not action or action not in known_tools:
+                # Strict mode: when the unknown `action` looks like a
+                # tool identifier (no spaces, short), assume the model
+                # was TRYING to call a tool and misnamed it. Feed an
+                # error observation back so the model can retry with
+                # a valid name, instead of collapsing to implicit-final
+                # after the very first mistake. The existing dup-guard
+                # + loop-level circuit breaker still bound retries.
+                # Only skipped when: strict mode is off, we've hit
+                # max_iterations, or the action is clearly the model's
+                # response text (contains a space → natural language).
+                looks_like_tool_id = (
+                    bool(action) and " " not in action and len(action) < 80
+                )
+                if (
+                    self.strict_tool_dispatch
+                    and looks_like_tool_id
+                    and count < self.max_iterations
+                ):
+                    available = sorted(known_tools)
+                    error_content = (
+                        f"[framework] error: '{action}' is not a "
+                        f"registered tool. Available tools: {available}. "
+                        f"Options: (1) call one of them with the correct "
+                        f"argument shape; (2) emit action=\"Final_Answer\" "
+                        f"with your final response text in action_input "
+                        f"if you're done."
+                    )
+                    tc_id = getattr(self, "_last_function_call_id", None) if self.use_function_calling else None
+                    err_msg = {
+                        "role": "tool" if tc_id else "function",
+                        "name": "tool_call_error",
+                        "content": error_content,
+                    }
+                    if tc_id:
+                        err_msg["tool_call_id"] = tc_id
+                    working_history.append(err_msg)
+                    yield {
+                        "type": "tool_result",
+                        "name": action,
+                        "result": error_content,
+                        "is_error": True,
+                    }
+                    if self.verbose:
+                        print(
+                            f"\x1B[1;33m[loop] strict-retry: action "
+                            f"'{action[:60]}' unknown; feeding error "
+                            f"back so the model can retry\x1B[0m"
+                        )
+                    self._last_function_call_id = None
+                    count += 1
+                    continue
+
+                # Non-strict OR strict-can't-help path: implicit-final.
+                # Prefer action_input; fall back to action-as-text ONLY
+                # when it's natural language (has spaces). NEVER leak
+                # Thought — it's internal reasoning that shouldn't reach
+                # a user, especially in third-person-persona apps.
+                if action_input and str(action_input).strip():
+                    final_answer = str(action_input)
+                elif action and action.strip() and " " in action:
+                    final_answer = str(action)
+                else:
+                    final_answer = (
+                        "(agent emitted an unrecognized action and no "
+                        "answer text — try rephrasing or re-run)"
+                    )
+                if self.verbose:
+                    preview = (action or "<empty>")[:60]
+                    print(
+                        f"\x1B[1;33m[loop] implicit-final: action "
+                        f"'{preview}' is not a registered tool and not "
+                        f"a Final_Answer variant; returning "
+                        f"action_input as final (Thought NOT leaked)"
+                        f"\x1B[0m"
+                    )
+                yield {"type": "final", "content": final_answer}
+                break
+
             yield {"type": "tool_call", "name": action, "args": action_input}
             if self.verbose:
                 print(f"\x1B[3;33m[tool] Invoking '{action}' with args: {action_input}\x1B[0m")

{agentx_dev-3.0.3 → agentx_dev-3.0.5}/agentx_dev/Runner/AsyncAgentRun.py

@@ -86,6 +86,7 @@ class AsyncAgentRunner:
         agent: AgentFormattor | AgentPrompt | str | None = None,
         permissions: Any = None,
         include_denied_tools: bool = False,
+        strict_tool_dispatch: bool = False,
     ):
         if Agent is not None and agent is not None:
             raise TypeError("AsyncAgentRunner received both 'Agent' and 'agent'; pass only one.")
@@ -133,6 +134,8 @@ class AsyncAgentRunner:
                 "are mutually exclusive. Function-calling routes through the "
                 "AgentType parser; native binding skips it. Pick one."
             )
+        # See AgentRunner.__init__ for the strict_tool_dispatch contract.
+        self.strict_tool_dispatch = strict_tool_dispatch
 
         self.auto_cache = auto_cache and config.caching_enabled
         self.auto_memory = auto_memory and config.memory_enabled
@@ -506,29 +509,79 @@ class AsyncAgentRunner:
             elif thought:
                 logger.info(f"thought: {thought}")
 
-            # Implicit-final guardrail: `action` is empty OR not a
-            # registered tool AND not a Final_Answer variant. Route to
-            # Final_Answer built from the text the model provided.
+            # Strip OpenAI's "functions." prefix before the known-tools
+            # check — otherwise a valid tool call falls through to the
+            # implicit-final guardrail and leaks Thought as user text.
+            normalized_action = self.registry._normalize_tool_name(action)
+            if normalized_action != action:
+                if self.verbose:
+                    print(
+                        f"\x1B[3;33m[loop] normalized action "
+                        f"'{action}' -> '{normalized_action}'\x1B[0m"
+                    )
+                action = normalized_action
+
+            # Implicit-final guardrail — see the sync AgentRunner for
+            # the full rationale. If strict_tool_dispatch=True AND the
+            # unknown action looks like a tool identifier (no spaces)
+            # AND we still have iteration budget, feed an error
+            # observation back to the model and let it retry.
             known_tools = set(self.registry.sync_std) | set(self.registry.sync_struct) \
                         | set(self.registry.async_std) | set(self.registry.async_struct)
             if not action or action not in known_tools:
-                parts: List[str] = []
-                if thought:
-                    parts.append(str(thought))
-                if action and action.strip():
-                    parts.append(str(action))
-                if action_input and str(action_input).strip():
-                    parts.append(str(action_input))
-                final_answer = "\n\n".join(parts) or (
-                    "(agent emitted an unrecognized action and no text)"
+                looks_like_tool_id = (
+                    bool(action) and " " not in action and len(action) < 80
                 )
+                if (
+                    self.strict_tool_dispatch
+                    and looks_like_tool_id
+                    and count < self.max_iterations
+                ):
+                    available = sorted(known_tools)
+                    error_content = (
+                        f"[framework] error: '{action}' is not a "
+                        f"registered tool. Available tools: {available}. "
+                        f"Options: (1) call one of them with the correct "
+                        f"argument shape; (2) emit action=\"Final_Answer\" "
+                        f"with your final response text in action_input "
+                        f"if you're done."
+                    )
+                    tc_id = getattr(self, "_last_function_call_id", None) if self.use_function_calling else None
+                    err_msg = {
+                        "role": "tool" if tc_id else "function",
+                        "name": "tool_call_error",
+                        "content": error_content,
+                    }
+                    if tc_id:
+                        err_msg["tool_call_id"] = tc_id
+                    working_history.append(err_msg)
+                    if self.verbose:
+                        print(
+                            f"\x1B[1;33m[loop] strict-retry: action "
+                            f"'{action[:60]}' unknown; feeding error "
+                            f"back so the model can retry\x1B[0m"
+                        )
+                    self._last_function_call_id = None
+                    count += 1
+                    continue
+
+                # Non-strict OR strict-can't-help: implicit-final.
+                if action_input and str(action_input).strip():
+                    final_answer = str(action_input)
+                elif action and action.strip() and " " in action:
+                    final_answer = str(action)
+                else:
+                    final_answer = (
+                        "(agent emitted an unrecognized action and no "
+                        "answer text — try rephrasing or re-run)"
+                    )
                 if self.verbose:
                     preview = (action or "<empty>")[:60]
                     print(
                         f"\x1B[1;33m[loop] implicit-final: action "
                         f"'{preview}' is not a registered tool and not "
-                        f"a Final_Answer variant; treating turn as "
-                        f"Final_Answer\x1B[0m"
+                        f"a Final_Answer variant; returning action_input "
+                        f"as final (Thought NOT leaked)\x1B[0m"
                     )
                 break
 

{agentx_dev-3.0.3 → agentx_dev-3.0.5/agentx_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentx-dev
-Version: 3.0.3
+Version: 3.0.5
 Summary: A lightweight LLM agent framework with multi-agent orchestration (Supervisor + dynamic specialist spawning), permission-gated default tools, MCP integration, and prompt-template presets.
 Author-email: Bruce-Arhin Shadrach <brucearhin098@gmail.com>
 License: MIT License

{agentx_dev-3.0.3 → agentx_dev-3.0.5}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 
 name = "agentx-dev"
-version = "3.0.3"
+version = "3.0.5"
 description = "A lightweight LLM agent framework with multi-agent orchestration (Supervisor + dynamic specialist spawning), permission-gated default tools, MCP integration, and prompt-template presets."
 authors = [{ name = "Bruce-Arhin Shadrach", email = "brucearhin098@gmail.com" }]
 # Best practice: link to the license file