deepagents 0.3.6__py3-none-any.whl → 0.3.7__py3-none-any.whl

deepagents/middleware/skills.py

@@ -114,6 +114,8 @@ from langchain_core.runnables import RunnableConfig
 from langgraph.prebuilt import ToolRuntime
 from langgraph.runtime import Runtime
 
+from deepagents.middleware._utils import append_to_system_message
+
 logger = logging.getLogger(__name__)
 
 # Security: Maximum size for SKILL.md files to prevent DoS attacks (10MB)
@@ -558,18 +560,20 @@ class SkillsMiddleware(AgentMiddleware):
         lines = []
         for skill in skills:
             lines.append(f"- **{skill['name']}**: {skill['description']}")
+            if skill["allowed_tools"]:
+                lines.append(f"  -> Allowed tools: {', '.join(skill['allowed_tools'])}")
             lines.append(f"  -> Read `{skill['path']}` for full instructions")
 
         return "\n".join(lines)
 
     def modify_request(self, request: ModelRequest) -> ModelRequest:
-        """Inject skills documentation into a model request's system prompt.
+        """Inject skills documentation into a model request's system message.
 
         Args:
             request: Model request to modify
 
         Returns:
-            New model request with skills documentation injected into system prompt
+            New model request with skills documentation injected into system message
         """
         skills_metadata = request.state.get("skills_metadata", [])
         skills_locations = self._format_skills_locations()
@@ -580,12 +584,9 @@ class SkillsMiddleware(AgentMiddleware):
             skills_list=skills_list,
         )
 
-        if request.system_prompt:
-            system_prompt = request.system_prompt + "\n\n" + skills_section
-        else:
-            system_prompt = skills_section
+        new_system_message = append_to_system_message(request.system_message, skills_section)
 
-        return request.override(system_prompt=system_prompt)
+        return request.override(system_message=new_system_message)
 
     def before_agent(self, state: SkillsState, runtime: Runtime, config: RunnableConfig) -> SkillsStateUpdate | None:
         """Load skills metadata before agent execution (synchronous).
@@ -602,7 +603,7 @@ class SkillsMiddleware(AgentMiddleware):
             config: Runnable config.
 
         Returns:
-            State update with skills_metadata populated, or None if already present
+            State update with `skills_metadata` populated, or `None` if already present
         """
         # Skip if skills_metadata is already present in state (even if empty)
         if "skills_metadata" in state:
@@ -637,7 +638,7 @@ class SkillsMiddleware(AgentMiddleware):
             config: Runnable config.
 
         Returns:
-            State update with skills_metadata populated, or None if already present
+            State update with `skills_metadata` populated, or `None` if already present
         """
         # Skip if skills_metadata is already present in state (even if empty)
         if "skills_metadata" in state:

deepagents/middleware/subagents.py

@@ -1,7 +1,7 @@
 """Middleware for providing subagents to an agent via a `task` tool."""
 
 from collections.abc import Awaitable, Callable, Sequence
-from typing import Any, NotRequired, TypedDict, cast
+from typing import Annotated, Any, NotRequired, TypedDict, cast
 
 from langchain.agents import create_agent
 from langchain.agents.middleware import HumanInTheLoopMiddleware, InterruptOnConfig
@@ -13,6 +13,8 @@ from langchain_core.runnables import Runnable
 from langchain_core.tools import StructuredTool
 from langgraph.types import Command
 
+from deepagents.middleware._utils import append_to_system_message
+
 
 class SubAgent(TypedDict):
     """Specification for an agent.
@@ -71,10 +73,14 @@ class SubAgent(TypedDict):
 class CompiledSubAgent(TypedDict):
     """A pre-compiled agent spec.
 
-    Important: The runnable's state schema must include a 'messages' key.
-    This is required for the subagent to communicate results back to the main agent.
+    !!! note
+
+        The runnable's state schema must include a 'messages' key.
+
+        This is required for the subagent to communicate results back to the main agent.
+
     When the subagent completes, the final message in the 'messages' list will be
-    extracted and returned as a ToolMessage to the parent agent.
+    extracted and returned as a `ToolMessage` to the parent agent.
     """
 
     name: str
@@ -84,7 +90,16 @@ class CompiledSubAgent(TypedDict):
     """What this subagent does."""
 
     runnable: Runnable
-    """The Runnable to use for the agent. Must return a state with a 'messages' key."""
+    """A custom agent implementation.
+
+    Create a custom agent using either:
+
+    1. LangChain's [`create_agent()`](https://docs.langchain.com/oss/python/langchain/quickstart)
+    2. A custom graph using [`langgraph`](https://docs.langchain.com/oss/python/langgraph/quickstart)
+
+    If you're creating a custom graph, make sure the state schema includes a 'messages' key.
+    This is required for the subagent to communicate results back to the main agent.
+    """
 
 
 DEFAULT_SUBAGENT_PROMPT = "In order to complete the objective that the user asks of you, you have access to a number of standard tools."
@@ -384,8 +399,11 @@ def _create_task_tool(
         task_description = task_description.format(available_agents=subagent_description_str)
 
     def task(
-        description: str,
-        subagent_type: str,
+        description: Annotated[
+            str,
+            "A detailed description of the task for the subagent to perform autonomously. Include all necessary context and specify the expected output format.",  # noqa: E501
+        ],
+        subagent_type: Annotated[str, "The type of subagent to use. Must be one of the available agent types listed in the tool description."],
         runtime: ToolRuntime,
     ) -> str | Command:
         if subagent_type not in subagent_graphs:
@@ -399,8 +417,11 @@ def _create_task_tool(
         return _return_command_with_state_update(result, runtime.tool_call_id)
 
     async def atask(
-        description: str,
-        subagent_type: str,
+        description: Annotated[
+            str,
+            "A detailed description of the task for the subagent to perform autonomously. Include all necessary context and specify the expected output format.",  # noqa: E501
+        ],
+        subagent_type: Annotated[str, "The type of subagent to use. Must be one of the available agent types listed in the tool description."],
         runtime: ToolRuntime,
     ) -> str | Command:
         if subagent_type not in subagent_graphs:
@@ -439,18 +460,24 @@ class SubAgentMiddleware(AgentMiddleware):
 
     Args:
         default_model: The model to use for subagents.
-            Can be a LanguageModelLike or a dict for init_chat_model.
+
+            Can be a `LanguageModelLike` or a dict for `init_chat_model`.
         default_tools: The tools to use for the default general-purpose subagent.
-        default_middleware: Default middleware to apply to all subagents. If `None` (default),
-            no default middleware is applied. Pass a list to specify custom middleware.
-        default_interrupt_on: The tool configs to use for the default general-purpose subagent. These
-            are also the fallback for any subagents that don't specify their own tool configs.
+        default_middleware: Default middleware to apply to all subagents.
+
+            If `None`, no default middleware is applied.
+
+            Pass a list to specify custom middleware.
+        default_interrupt_on: The tool configs to use for the default general-purpose subagent.
+
+            These are also the fallback for any subagents that don't specify their own tool configs.
         subagents: A list of additional subagents to provide to the agent.
         system_prompt: Full system prompt override. When provided, completely replaces
             the agent's system prompt.
-        general_purpose_agent: Whether to include the general-purpose agent. Defaults to `True`.
-        task_description: Custom description for the task tool. If `None`, uses the
-            default description template.
+        general_purpose_agent: Whether to include the general-purpose agent.
+        task_description: Custom description for the task tool.
+
+            If `None`, uses the default description template.
 
     Example:
         ```python
@@ -494,7 +521,7 @@ class SubAgentMiddleware(AgentMiddleware):
         general_purpose_agent: bool = True,
         task_description: str | None = None,
     ) -> None:
-        """Initialize the SubAgentMiddleware."""
+        """Initialize the `SubAgentMiddleware`."""
         super().__init__()
         self.system_prompt = system_prompt
         task_tool = _create_task_tool(
@@ -513,10 +540,10 @@ class SubAgentMiddleware(AgentMiddleware):
         request: ModelRequest,
         handler: Callable[[ModelRequest], ModelResponse],
     ) -> ModelResponse:
-        """Update the system prompt to include instructions on using subagents."""
+        """Update the system message to include instructions on using subagents."""
         if self.system_prompt is not None:
-            system_prompt = request.system_prompt + "\n\n" + self.system_prompt if request.system_prompt else self.system_prompt
-            return handler(request.override(system_prompt=system_prompt))
+            new_system_message = append_to_system_message(request.system_message, self.system_prompt)
+            return handler(request.override(system_message=new_system_message))
         return handler(request)
 
     async def awrap_model_call(
@@ -524,8 +551,8 @@ class SubAgentMiddleware(AgentMiddleware):
         request: ModelRequest,
         handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
     ) -> ModelResponse:
-        """(async) Update the system prompt to include instructions on using subagents."""
+        """(async) Update the system message to include instructions on using subagents."""
         if self.system_prompt is not None:
-            system_prompt = request.system_prompt + "\n\n" + self.system_prompt if request.system_prompt else self.system_prompt
-            return await handler(request.override(system_prompt=system_prompt))
+            new_system_message = append_to_system_message(request.system_message, self.system_prompt)
+            return await handler(request.override(system_message=new_system_message))
         return await handler(request)