agent-wait 0.6.0__tar.gz → 0.7.0__tar.gz

{agent_wait-0.6.0 → agent_wait-0.7.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: agent-wait
-Version: 0.6.0
-Summary: Human-in-the-loop for LangGraph and Pydantic AI agents -- and anything else a run has to wait for. Get the interrupt out of the process (SNS, SQS, EventBridge, DynamoDB, webhook) with everything needed to answer it; get the answer back in.
+Version: 0.7.0
+Summary: Human-in-the-loop for LangGraph, Pydantic AI and Strands agents -- and anything else a run has to wait for. Get the interrupt out of the process (SNS, SQS, EventBridge, DynamoDB, webhook) with everything needed to answer it; get the answer back in.
 Project-URL: Homepage, https://skamalj.github.io/agent-wait/
 Project-URL: Documentation, https://skamalj.github.io/agent-wait/
 Project-URL: Source, https://github.com/skamalj/agent-wait
@@ -10,7 +10,7 @@ Project-URL: Changelog, https://github.com/skamalj/agent-wait/blob/main/CHANGELO
 Author-email: Kamaljeet Singh <skamalj@gmail.com>
 License-Expression: MIT
 License-File: LICENSE
-Keywords: agents,approval,callback,durable,dynamodb,eventbridge,hitl,human-in-the-loop,interrupt,lambda,langchain,langgraph,pydantic-ai,serverless,sns,sqs,webhook
+Keywords: agents,approval,callback,durable,dynamodb,eventbridge,hitl,human-in-the-loop,interrupt,lambda,langchain,langgraph,pydantic-ai,serverless,sns,sqs,strands,webhook
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -24,12 +24,15 @@ Provides-Extra: all
 Requires-Dist: boto3>=1.35; extra == 'all'
 Requires-Dist: langgraph<2,>=1.2; extra == 'all'
 Requires-Dist: pydantic-ai-slim<3,>=2.43; extra == 'all'
+Requires-Dist: strands-agents<2,>=1.55; extra == 'all'
 Provides-Extra: aws
 Requires-Dist: boto3>=1.35; extra == 'aws'
 Provides-Extra: langgraph
 Requires-Dist: langgraph<2,>=1.2; extra == 'langgraph'
 Provides-Extra: pydantic-ai
 Requires-Dist: pydantic-ai-slim<3,>=2.43; extra == 'pydantic-ai'
+Provides-Extra: strands
+Requires-Dist: strands-agents<2,>=1.55; extra == 'strands'
 Description-Content-Type: text/markdown
 
 # agent-wait
@@ -46,8 +49,8 @@ deploy. But the same shape covers a vendor callback, a payment processor, a KYC
 another agent — anything the run cannot continue without, and nothing inside the process
 can supply.
 
-LangGraph has `interrupt()` for this; Pydantic AI has `ApprovalRequired`. In both, the
-run pauses and the question is handed to whatever called it — and that is where the
+LangGraph has `interrupt()` for this; Pydantic AI has `ApprovalRequired`; Strands has
+`tool_context.interrupt()`. In all of them the run pauses and the question is handed to whatever called it — and that is where the
 framework stops. There is no built-in way to tell anyone *else* that a question was asked,
 and no built-in way for anyone else to answer it. The moment the question has to reach
 Slack, an approvals dashboard, a ticket queue or another service, you are writing that
@@ -61,11 +64,14 @@ it in one envelope, and documents the shape of the answer so the return leg is o
 ```bash
 pip install "agent-wait[langgraph]"        # @wait + publish_interrupts for LangGraph
 pip install "agent-wait[pydantic-ai]"      # the same two names for Pydantic AI
+pip install "agent-wait[strands]"          # ... and for Strands Agents
 pip install "agent-wait[langgraph,aws]"    # + SNS / SQS / EventBridge / DynamoDB announcers
 ```
 
 The bare `agent-wait` is the framework-free core (policy, envelope, webhook and in-memory
-announcers) and depends on nothing. Each extra pulls in exactly one framework or provider.
+announcers) and depends on nothing. Each extra pulls in exactly one framework or provider —
+the full list, with what each framework leaves to you:
+[Frameworks and providers](https://skamalj.github.io/agent-wait/frameworks-and-providers/).
 
 ## The whole thing
 
@@ -194,6 +200,40 @@ only if the history you pass already holds the tool's return. `requires_approval
 tools and `CallDeferred` calls (a job handed to an external system) are published too,
 with the default policy.
 
+## The same two names on Strands
+
+```python
+from agent_wait.strands import publish_interrupts, wait
+from strands import Agent, tool
+from strands.session.file_session_manager import FileSessionManager
+from strands.types.tools import ToolContext
+
+
+@tool(context=True)
+@wait(FINANCE)
+def issue_refund(order_id: str, amount: int, tool_context: ToolContext) -> str:
+    payments.refund(order_id, amount)
+    return "refunded"
+
+
+agent = Agent(tools=[issue_refund], session_manager=FileSessionManager(session_id=thread_id))
+result = agent("refund order 4471")
+publish_interrupts(result, agent.session_id, announce=[SnsAnnounce(topic_arn)])
+```
+
+The run stops with `result.stop_reason == "interrupt"`; `question_id` is the interrupt id
+(one per tool call). The answer goes back through the framework's own resume, verbatim:
+
+```python
+agent = Agent(tools=[issue_refund], session_manager=FileSessionManager(session_id=thread_id))
+result = agent([{"interruptResponse": {"interruptId": question_id, "response": answer}}])
+```
+
+Two rules the framework leaves to you: `@tool(context=True)` with the parameter named
+`tool_context`, and a session manager — that is what keeps the parked question alive
+between the return and the resume. A second answer after the run has moved on raises
+(`ValueError`), so a host that may see duplicates checks `stop_reason` first or catches.
+
 ## Async mode — the thread does not park
 
 ```python
@@ -291,14 +331,15 @@ agent_wait              core: WaitPolicy, Question, the envelope, publish(), Bas
                         Webhook/Log/InMemory announcers, and the Framework interface. No deps.
 agent_wait.langgraph    [langgraph]    @wait and publish_interrupts() bound to LangGraph.
 agent_wait.pydantic_ai  [pydantic-ai]  the same two names bound to Pydantic AI's deferred tools.
+agent_wait.strands      [strands]      the same two names bound to Strands' tool_context.interrupt().
 agent_wait.aws          [aws]          SnsAnnounce, SqsAnnounce, EventBridgeAnnounce, DynamoDbAnnounce.
 examples/refund_agent   a graph, a host written for Lambda behind SQS, and its CDK stack.
 docs/                   message contract, architecture, announcer guide, consumer guide.
 ```
 
 `@wait` and `publish_interrupts` are written once against a three-method `Framework`
-interface; `agent_wait.langgraph` and `agent_wait.pydantic_ai` are implementors of it,
-about fifty lines each. Announcers are the same split: `BaseAnnounce` is the interface,
+interface; `agent_wait.langgraph`, `agent_wait.pydantic_ai` and `agent_wait.strands` are
+implementors of it, thirty to fifty lines each. Announcers are the same split: `BaseAnnounce` is the interface,
 each provider subpackage the implementors. See
 [Architecture](https://skamalj.github.io/agent-wait/architecture/).
 

{agent_wait-0.6.0 → agent_wait-0.7.0}/README.md

@@ -12,8 +12,8 @@ deploy. But the same shape covers a vendor callback, a payment processor, a KYC
 another agent — anything the run cannot continue without, and nothing inside the process
 can supply.
 
-LangGraph has `interrupt()` for this; Pydantic AI has `ApprovalRequired`. In both, the
-run pauses and the question is handed to whatever called it — and that is where the
+LangGraph has `interrupt()` for this; Pydantic AI has `ApprovalRequired`; Strands has
+`tool_context.interrupt()`. In all of them the run pauses and the question is handed to whatever called it — and that is where the
 framework stops. There is no built-in way to tell anyone *else* that a question was asked,
 and no built-in way for anyone else to answer it. The moment the question has to reach
 Slack, an approvals dashboard, a ticket queue or another service, you are writing that
@@ -27,11 +27,14 @@ it in one envelope, and documents the shape of the answer so the return leg is o
 ```bash
 pip install "agent-wait[langgraph]"        # @wait + publish_interrupts for LangGraph
 pip install "agent-wait[pydantic-ai]"      # the same two names for Pydantic AI
+pip install "agent-wait[strands]"          # ... and for Strands Agents
 pip install "agent-wait[langgraph,aws]"    # + SNS / SQS / EventBridge / DynamoDB announcers
 ```
 
 The bare `agent-wait` is the framework-free core (policy, envelope, webhook and in-memory
-announcers) and depends on nothing. Each extra pulls in exactly one framework or provider.
+announcers) and depends on nothing. Each extra pulls in exactly one framework or provider —
+the full list, with what each framework leaves to you:
+[Frameworks and providers](https://skamalj.github.io/agent-wait/frameworks-and-providers/).
 
 ## The whole thing
 
@@ -160,6 +163,40 @@ only if the history you pass already holds the tool's return. `requires_approval
 tools and `CallDeferred` calls (a job handed to an external system) are published too,
 with the default policy.
 
+## The same two names on Strands
+
+```python
+from agent_wait.strands import publish_interrupts, wait
+from strands import Agent, tool
+from strands.session.file_session_manager import FileSessionManager
+from strands.types.tools import ToolContext
+
+
+@tool(context=True)
+@wait(FINANCE)
+def issue_refund(order_id: str, amount: int, tool_context: ToolContext) -> str:
+    payments.refund(order_id, amount)
+    return "refunded"
+
+
+agent = Agent(tools=[issue_refund], session_manager=FileSessionManager(session_id=thread_id))
+result = agent("refund order 4471")
+publish_interrupts(result, agent.session_id, announce=[SnsAnnounce(topic_arn)])
+```
+
+The run stops with `result.stop_reason == "interrupt"`; `question_id` is the interrupt id
+(one per tool call). The answer goes back through the framework's own resume, verbatim:
+
+```python
+agent = Agent(tools=[issue_refund], session_manager=FileSessionManager(session_id=thread_id))
+result = agent([{"interruptResponse": {"interruptId": question_id, "response": answer}}])
+```
+
+Two rules the framework leaves to you: `@tool(context=True)` with the parameter named
+`tool_context`, and a session manager — that is what keeps the parked question alive
+between the return and the resume. A second answer after the run has moved on raises
+(`ValueError`), so a host that may see duplicates checks `stop_reason` first or catches.
+
 ## Async mode — the thread does not park
 
 ```python
@@ -257,14 +294,15 @@ agent_wait              core: WaitPolicy, Question, the envelope, publish(), Bas
                         Webhook/Log/InMemory announcers, and the Framework interface. No deps.
 agent_wait.langgraph    [langgraph]    @wait and publish_interrupts() bound to LangGraph.
 agent_wait.pydantic_ai  [pydantic-ai]  the same two names bound to Pydantic AI's deferred tools.
+agent_wait.strands      [strands]      the same two names bound to Strands' tool_context.interrupt().
 agent_wait.aws          [aws]          SnsAnnounce, SqsAnnounce, EventBridgeAnnounce, DynamoDbAnnounce.
 examples/refund_agent   a graph, a host written for Lambda behind SQS, and its CDK stack.
 docs/                   message contract, architecture, announcer guide, consumer guide.
 ```
 
 `@wait` and `publish_interrupts` are written once against a three-method `Framework`
-interface; `agent_wait.langgraph` and `agent_wait.pydantic_ai` are implementors of it,
-about fifty lines each. Announcers are the same split: `BaseAnnounce` is the interface,
+interface; `agent_wait.langgraph`, `agent_wait.pydantic_ai` and `agent_wait.strands` are
+implementors of it, thirty to fifty lines each. Announcers are the same split: `BaseAnnounce` is the interface,
 each provider subpackage the implementors. See
 [Architecture](https://skamalj.github.io/agent-wait/architecture/).
 

{agent_wait-0.6.0 → agent_wait-0.7.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "agent-wait"
-version = "0.6.0"
-description = "Human-in-the-loop for LangGraph and Pydantic AI agents -- and anything else a run has to wait for. Get the interrupt out of the process (SNS, SQS, EventBridge, DynamoDB, webhook) with everything needed to answer it; get the answer back in."
+version = "0.7.0"
+description = "Human-in-the-loop for LangGraph, Pydantic AI and Strands agents -- and anything else a run has to wait for. Get the interrupt out of the process (SNS, SQS, EventBridge, DynamoDB, webhook) with everything needed to answer it; get the answer back in."
 readme = "README.md"
 requires-python = ">=3.12"
 license = "MIT"
@@ -14,6 +14,7 @@ keywords = [
     "langgraph",
     "langchain",
     "pydantic-ai",
+    "strands",
     "agents",
     "interrupt",
     "durable",
@@ -41,8 +42,9 @@ dependencies = []
 [project.optional-dependencies]
 langgraph = ["langgraph>=1.2,<2"]
 pydantic-ai = ["pydantic-ai-slim>=2.43,<3"]
+strands = ["strands-agents>=1.55,<2"]
 aws = ["boto3>=1.35"]
-all = ["agent-wait[langgraph,pydantic-ai,aws]"]
+all = ["agent-wait[langgraph,pydantic-ai,strands,aws]"]
 
 [project.urls]
 Homepage = "https://skamalj.github.io/agent-wait/"

{agent_wait-0.6.0 → agent_wait-0.7.0}/src/agent_wait/__init__.py

@@ -12,10 +12,10 @@
     publish_interrupts(result, thread_id, announce=[SnsAnnounce(topic_arn)])
 
 The core is framework- and provider-neutral: the policy, the question, the envelope,
-`publish()`, and the announcer interface. `agent_wait.langgraph` and
-`agent_wait.pydantic_ai` implement the `Framework` interface for LangGraph and Pydantic
-AI; `agent_wait.aws` implements announcers for AWS. Install the extras you need:
-`pip install agent-wait[langgraph,aws]` or `agent-wait[pydantic-ai,aws]`.
+`publish()`, and the announcer interface. `agent_wait.langgraph`, `agent_wait.pydantic_ai`
+and `agent_wait.strands` implement the `Framework` interface for LangGraph, Pydantic AI
+and Strands Agents; `agent_wait.aws` implements announcers for AWS. Install the extras
+you need: `pip install agent-wait[langgraph,aws]`, `[pydantic-ai,aws]`, `[strands,aws]`.
 """
 
 from .announce import (
@@ -48,7 +48,7 @@ from .policy import WaitPolicy, parse_duration
 from .publish import build_envelope, publish
 from .wait import make_publish_interrupts, make_wait, question_id_for
 
-__version__ = "0.6.0"
+__version__ = "0.7.0"
 
 __all__ = [
     "MAX_QUESTION_BYTES",

agent_wait-0.7.0/src/agent_wait/strands/__init__.py

@@ -0,0 +1,93 @@
+"""Strands Agents implementor of `agent_wait.framework.Framework`, and the bound names.
+
+    from agent_wait.strands import wait, publish_interrupts
+
+Install with `pip install agent-wait[strands]`.
+
+## What Strands provides, and what we use
+
+- **Park:** a tool declared `@tool(context=True)` receives a `ToolContext`;
+  `tool_context.interrupt(name, reason=value)` raises `InterruptException` the first
+  time and returns the human's response when the tool runs again after resume. The id
+  is `v1:tool_call:<toolUseId>:<uuid5(name)>` -- one per tool call, no collisions.
+- **Read back:** `result.stop_reason == "interrupt"` and `result.interrupts`, each an
+  `Interrupt(id, name, reason, response)`. `reason` is what we parked on, verbatim.
+- **Thread:** `agent.session_id` -- the session manager's id when one is attached, a
+  random per-instance id otherwise.
+- **Resume** (the host's call, not ours):
+
+      agent([{"interruptResponse": {"interruptId": question_id, "response": answer}}])
+
+  The tool runs again, `interrupt()` returns `answer`, and the `@wait` wrapper applies
+  its usual rules.
+
+## Three things to know
+
+- **`@tool(context=True)` and name the parameter `tool_context`.** The wrapper hides it
+  from the published `args` by that name; Strands injects it by that name.
+- **A session manager is what makes the wait durable.** Interrupt state lives on the
+  agent instance and is persisted by `FileSessionManager` / `S3SessionManager` (or
+  your own) between the return and the resume. Without one, the parked question dies
+  with the process.
+- **A duplicate answer is refused, not ignored.** Resuming a run that is not parked
+  raises `ValueError("... not in interrupt state")`; an unknown id raises `KeyError`;
+  a plain prompt to a parked run raises `TypeError`. None of them runs anything. The
+  host checks `result.stop_reason` (or its own record) before resuming, or catches.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+try:
+    from strands.types.tools import ToolContext
+except ImportError as _err:  # pragma: no cover - exercised only without the extra
+    raise ImportError("agent_wait.strands needs Strands Agents: pip install 'agent-wait[strands]'") from _err
+
+from ..framework import Framework
+from ..wait import make_publish_interrupts, make_wait
+
+__all__ = ["StrandsFramework", "publish_interrupts", "questions_in", "wait"]
+
+INTERRUPT_NAME = "agent_wait"
+
+
+def _tool_context(call_args: Mapping[str, Any]) -> ToolContext[Any] | None:
+    for value in call_args.values():
+        if isinstance(value, ToolContext):
+            return value  # pyright: ignore[reportUnknownVariableType]
+    return None
+
+
+class StrandsFramework(Framework):
+    name = "strands"
+    hidden_params = ("tool_context",)
+
+    def interrupt(self, value: Mapping[str, Any], call_args: Mapping[str, Any]) -> Any:
+        ctx = _tool_context(call_args)
+        if ctx is None:
+            raise TypeError(
+                "a @wait tool on Strands needs `@tool(context=True)` and a `tool_context` parameter"
+            )
+        return ctx.interrupt(INTERRUPT_NAME, reason=dict(value))
+
+    def interrupts_in(self, result: Any) -> list[tuple[str, Any]]:
+        if getattr(result, "stop_reason", None) != "interrupt":
+            return []
+        interrupts: Any = getattr(result, "interrupts", None) or ()
+        return [(str(item.id), item.reason) for item in interrupts]
+
+    def current_thread_id(self, call_args: Mapping[str, Any]) -> str:
+        ctx = _tool_context(call_args)
+        session_id: Any = getattr(getattr(ctx, "agent", None), "session_id", None)
+        if not session_id:
+            raise RuntimeError("@wait(mode='async') on Strands needs the agent's session_id")
+        return str(session_id)
+
+
+_framework = StrandsFramework()
+
+wait = make_wait(_framework)
+publish_interrupts = make_publish_interrupts(_framework)
+questions_in = publish_interrupts.questions_in  # type: ignore[attr-defined]