flowforge-sdk 0.3.2__tar.gz → 0.3.4__tar.gz

{flowforge_sdk-0.3.2 → flowforge_sdk-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowforge-sdk
-Version: 0.3.2
+Version: 0.3.4
 Summary: Python SDK for FlowForge - AI workflow orchestration
 Project-URL: Homepage, https://github.com/flowforge/flowforge
 Project-URL: Documentation, https://flowforge.dev/docs

{flowforge_sdk-0.3.2 → flowforge_sdk-0.3.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flowforge-sdk"
-version = "0.3.2"
+version = "0.3.4"
 description = "Python SDK for FlowForge - AI workflow orchestration"
 readme = "README.md"
 requires-python = ">=3.11"

{flowforge_sdk-0.3.2 → flowforge_sdk-0.3.4}/src/flowforge/__init__.py

@@ -27,7 +27,7 @@ from flowforge.exceptions import (
 from flowforge.network import Network, NetworkResult, NetworkState, RouterContext, network
 from flowforge.steps import step
 from flowforge.streaming import RunEvent, RunEventType
-from flowforge.tools import Tool, tool
+from flowforge.tools import SubAgentConfig, Tool, sub_agent, tool
 from flowforge.triggers import Trigger, trigger
 
 __version__ = "0.1.0"
@@ -45,6 +45,8 @@ __all__ = [
     # Tools
     "Tool",
     "tool",
+    "sub_agent",
+    "SubAgentConfig",
     # Agent
     "AgentConfig",
     "AgentState",

{flowforge_sdk-0.3.2 → flowforge_sdk-0.3.4}/src/flowforge/steps.py

@@ -11,7 +11,7 @@ from flowforge.agent_def import AgentDefinition
 from flowforge.exceptions import StepCompleted, StepFailed
 from flowforge.network import Network, NetworkResult, NetworkState, RouterContext
 from flowforge.router import LLMRouter
-from flowforge.tools import Tool
+from flowforge.tools import SubAgentConfig, Tool
 
 T = TypeVar("T")
 
@@ -458,6 +458,8 @@ class StepManager:
         checkpoint_strategy: str = "per_tool",
         max_tool_calls: int = 50,
         temperature: float = 0.7,
+        _depth: int = 0,
+        _max_depth: int = 3,
         **kwargs: Any,
     ) -> AgentResult:
         """
@@ -467,6 +469,9 @@ class StepManager:
         until the task is complete or limits are reached. Each tool execution
         is checkpointed for durability.
 
+        Sub-agent tools (created via ``sub_agent()``) are automatically
+        detected and executed as nested agent loops.
+
         Args:
             step_id: Unique identifier for this agent execution.
             task: The task/prompt for the agent to accomplish.
@@ -480,6 +485,8 @@ class StepManager:
                 - "final_only": Only checkpoint final result
             max_tool_calls: Maximum total tool calls across iterations (default 50).
             temperature: Sampling temperature for LLM (default 0.7).
+            _depth: Current nesting depth (internal, used by sub-agent recursion).
+            _max_depth: Maximum allowed nesting depth (default 3).
             **kwargs: Additional LLM parameters.
 
         Returns:
@@ -667,6 +674,88 @@ class StepManager:
                 # Execute tool via step.run for checkpointing
                 tool_step_id = f"{step_id}/iter-{state.iteration}/tool-{tool_call_id}"
 
+                # --- Sub-agent interception ---
+                # If the tool is a sub-agent wrapper, run a nested agent
+                # loop instead of calling tool.fn directly.
+                cfg: SubAgentConfig | None = getattr(tool, "_sub_agent_config", None)
+                if cfg is not None:
+                    # Depth guard: prevent infinite sub-agent recursion
+                    if _depth >= _max_depth:
+                        error_message = json.dumps({
+                            "error": f"Sub-agent depth limit reached ({_max_depth}). "
+                            "Cannot spawn further sub-agents.",
+                        })
+                        state.messages.append({
+                            "role": "tool",
+                            "tool_call_id": tool_call_id,
+                            "name": tool_name,
+                            "content": error_message,
+                        })
+                        tool_call_record["status"] = "failed"
+                        tool_call_record["error"] = "depth_limit_reached"
+                        state.tool_calls_count += 1
+                        continue
+
+                    sub_step_id = f"{step_id}/sub-{cfg.agent.name}-{tool_call_id}"
+
+                    # Build sub-agent system prompt with optional parent context
+                    sub_system = cfg.agent.system
+                    if cfg.context_mode == "summary":
+                        recent = state.messages[-6:]  # last 3 exchanges
+                        context_lines = [
+                            f"[{m['role']}]: {str(m.get('content', ''))[:200]}"
+                            for m in recent
+                        ]
+                        sub_system += "\n\nParent context:\n" + "\n".join(context_lines)
+                    elif cfg.context_mode == "full_history":
+                        sub_system += "\n\nFull parent conversation:\n" + json.dumps(state.messages)
+
+                    try:
+                        sub_result = await self.agent(
+                            sub_step_id,
+                            task=tool_args.get("task", ""),
+                            model=cfg.agent.model or model,
+                            system=sub_system,
+                            tools=cfg.agent.tools,
+                            max_iterations=cfg.max_iterations,
+                            max_tool_calls=cfg.max_tool_calls,
+                            temperature=cfg.temperature,
+                            _depth=_depth + 1,
+                            _max_depth=_max_depth,
+                            **kwargs,
+                        )
+                        sub_output = sub_result.output
+
+                        state.messages.append({
+                            "role": "tool",
+                            "tool_call_id": tool_call_id,
+                            "name": tool_name,
+                            "content": sub_output,
+                        })
+                        tool_call_record["status"] = "success"
+                        tool_call_record["result"] = sub_output
+                        tool_call_record["sub_agent"] = sub_result.to_dict()
+                    except StepCompleted:
+                        # Sub-agent completed its first execution — propagate
+                        # so the server can memoize the step. On replay the
+                        # nested agent() call returns normally.
+                        raise
+                    except (StepFailed, Exception) as e:
+                        err_msg = str(e)
+                        error_message = json.dumps({"error": err_msg})
+                        state.messages.append({
+                            "role": "tool",
+                            "tool_call_id": tool_call_id,
+                            "name": tool_name,
+                            "content": error_message,
+                        })
+                        tool_call_record["status"] = "failed"
+                        tool_call_record["error"] = err_msg
+
+                    state.tool_calls_count += 1
+                    continue
+                # --- End sub-agent interception ---
+
                 try:
                     tool_result = await self.run(
                         tool_step_id,
@@ -1129,6 +1218,8 @@ class _StepProxy:
         checkpoint_strategy: str = "per_tool",
         max_tool_calls: int = 50,
         temperature: float = 0.7,
+        _depth: int = 0,
+        _max_depth: int = 3,
         **kwargs: Any,
     ) -> AgentResult:
         return await self._get_manager().agent(
@@ -1141,6 +1232,8 @@ class _StepProxy:
             checkpoint_strategy=checkpoint_strategy,
             max_tool_calls=max_tool_calls,
             temperature=temperature,
+            _depth=_depth,
+            _max_depth=_max_depth,
             **kwargs,
         )
 

{flowforge_sdk-0.3.2 → flowforge_sdk-0.3.4}/src/flowforge/tools.py

@@ -1,10 +1,15 @@
 """Tool definition API for FlowForge agents."""
 
+from __future__ import annotations
+
 import inspect
 import types as _builtintypes
 from collections.abc import Awaitable, Callable
 from dataclasses import dataclass, field
-from typing import Any, Literal, Union, get_args, get_origin, get_type_hints
+from typing import TYPE_CHECKING, Any, Literal, Union, get_args, get_origin, get_type_hints
+
+if TYPE_CHECKING:
+    from flowforge.agent_def import AgentDefinition
 
 
 @dataclass
@@ -270,3 +275,110 @@ def tool(
         )
 
     return decorator
+
+
+@dataclass
+class SubAgentConfig:
+    """Configuration for a sub-agent tool.
+
+    This is attached to a Tool via ``_sub_agent_config`` so that
+    ``step.agent()`` can detect the tool as a sub-agent delegation
+    and run a nested agent loop instead of calling ``tool.fn``.
+
+    Attributes:
+        agent: The agent definition to run as a sub-agent.
+        max_iterations: Max iterations for the sub-agent loop.
+        max_tool_calls: Max tool calls for the sub-agent loop.
+        temperature: Sampling temperature for the sub-agent LLM.
+        context_mode: How much parent context to share with the sub-agent.
+    """
+
+    agent: AgentDefinition
+    max_iterations: int = 20
+    max_tool_calls: int = 50
+    temperature: float = 0.7
+    context_mode: Literal["task_only", "summary", "full_history"] = "task_only"
+
+
+def sub_agent(
+    agent: AgentDefinition,
+    *,
+    description: str | None = None,
+    max_iterations: int = 20,
+    max_tool_calls: int = 50,
+    temperature: float = 0.7,
+    context_mode: Literal["task_only", "summary", "full_history"] = "task_only",
+) -> Tool:
+    """Create a Tool that delegates work to a sub-agent.
+
+    When the parent agent's LLM calls this tool, ``step.agent()``
+    intercepts the call and runs a nested agent loop with the
+    given agent definition, returning the sub-agent's output as
+    the tool result.
+
+    Args:
+        agent: Agent definition describing the sub-agent.
+        description: Tool description shown to the LLM. If omitted,
+            auto-generated from the agent name and system prompt.
+        max_iterations: Maximum reasoning iterations for the sub-agent.
+        max_tool_calls: Maximum tool calls for the sub-agent.
+        temperature: Sampling temperature for the sub-agent.
+        context_mode: How much parent context to pass:
+            - "task_only" (default): Only the delegated task string.
+            - "summary": Task + last 3 parent exchanges as context.
+            - "full_history": Task + full parent conversation.
+
+    Returns:
+        A Tool with a single ``task: str`` parameter and a
+        ``_sub_agent_config`` attribute for detection.
+
+    Example:
+        researcher = agent_def(
+            name="researcher",
+            system="You research topics thoroughly.",
+            tools=[web_search],
+        )
+
+        research_tool = sub_agent(researcher, description="Delegate research tasks.")
+
+        result = await step.agent(
+            "manager",
+            task="Plan a project",
+            model="claude-opus-4-6",
+            tools=[research_tool],
+        )
+    """
+    desc = description or f"Delegate a task to the '{agent.name}' sub-agent. {agent.system[:100]}"
+
+    async def _placeholder(task: str) -> str:  # noqa: ARG001
+        raise RuntimeError(
+            "Sub-agent tool should not be called directly. "
+            "It is intercepted by step.agent()."
+        )
+
+    t = Tool(
+        name=agent.name,
+        description=desc,
+        fn=_placeholder,
+        parameters={
+            "type": "object",
+            "properties": {
+                "task": {
+                    "type": "string",
+                    "description": "The task to delegate to the sub-agent.",
+                },
+            },
+            "required": ["task"],
+        },
+    )
+
+    # Attach sub-agent config as a marker for step.agent() detection
+    t._sub_agent_config = SubAgentConfig(  # type: ignore[attr-defined]
+        agent=agent,
+        max_iterations=max_iterations,
+        max_tool_calls=max_tool_calls,
+        temperature=temperature,
+        context_mode=context_mode,
+    )
+
+    return t