agentapprovalprotocol 0.1.0__tar.gz

agentapprovalprotocol-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+node_modules/
+.next/
+out/
+.vercel/
+*.tsbuildinfo
+.DS_Store
+website/next-env.d.ts
+test-results/
+playwright-report/
+/aap
+/bin/
+/dist/
+/.wrangler/
+/sdk/python/.venv/
+/sdk/python/dist/
+/sdk/typescript/dist/
+__pycache__/
+/sdk/python/.pytest_cache/

agentapprovalprotocol-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.5
+Name: agentapprovalprotocol
+Version: 0.1.0
+Summary: Put an AI agent's tool calls behind an Agent Approval Protocol (AAP) approval provider.
+Project-URL: Homepage, https://agentapprovalprotocol.io
+Project-URL: Source, https://github.com/agentapprovalprotocol/agentapprovalprotocol
+License-Expression: Apache-2.0
+Keywords: aap,agents,ai,approval,human-in-the-loop
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: langgraph
+Requires-Dist: langchain>=1.0; extra == 'langgraph'
+Requires-Dist: langgraph>=1.0; extra == 'langgraph'
+Provides-Extra: pydantic-ai
+Requires-Dist: pydantic-ai-slim>=2.55; (python_full_version >= '3.11') and extra == 'pydantic-ai'
+Description-Content-Type: text/markdown
+
+# Agent Approval Protocol for Python
+
+Put an AI agent's tool calls behind an [AAP](https://agentapprovalprotocol.io) approval provider. Each call waits for the provider's decision, runs only if approved, and runs at most once.
+
+```sh
+pip install agentapprovalprotocol
+```
+
+## Check a tool call
+
+```python
+from agentapprovalprotocol import Call, Client, Gate
+
+gate = Gate(Client("https://approvals.example.com/api/aap", token))
+
+with gate.guard(Call(key=f"{run_id}:{tool_call.id}", tool=tool_call.name, arguments=tool_call.args)) as verdict:
+    if verdict:
+        result = run_tool(tool_call)
+    else:
+        result = verdict.reason  # return this to the model as the tool result
+```
+
+`key` must identify the tool call within its run, and stay the same if the call is seen again after a retry or resume. `guard` reports whether the tool succeeded when the block exits.
+
+`AsyncGate` and `AsyncClient` provide the same API for `asyncio`.
+
+## Pause instead of waiting
+
+With `mode="async"`, `check` returns `Pending` when there is no decision yet, so the run can pause and the process can exit. Mount a `Receiver` where the provider can reach it. When a decision arrives it wakes the run, and the gate checks the decision again before anything runs.
+
+Framework integrations handle pausing and resuming for you.
+
+## LangChain, LangGraph and Deep Agents
+
+```sh
+pip install "agentapprovalprotocol[langgraph]"
+```
+
+```python
+from agentapprovalprotocol.langgraph import ApprovalMiddleware
+
+approvals = ApprovalMiddleware("https://approvals.example.com/api/aap", token)
+agent = create_agent(model, tools=tools, middleware=[approvals])
+```
+
+Every tool call the agent makes goes to the provider. A denied call returns the reason to the model as the tool result.
+
+For Deep Agents, also add the middleware to every subagent:
+
+```python
+from agentapprovalprotocol.langgraph import deep_agent_subagents
+
+agent = create_deep_agent(model, tools=tools, middleware=[approvals], subagents=deep_agent_subagents(approvals, my_subagents))
+```
+
+To pause instead of waiting, use `ApprovalMiddleware(..., mode="async")` with a checkpointer, and mount a `Receiver` with `resumers={"langgraph": resumer(agent)}`. On LangSmith Deployment, use `deployment_resumer(get_client())` in a custom route instead. Resuming a thread any other way cannot approve a call: the middleware asks the provider again.
+
+## Pydantic AI
+
+```sh
+pip install "agentapprovalprotocol[pydantic-ai]"
+```
+
+Needs Python 3.11 or later.
+
+```python
+from agentapprovalprotocol.pydantic_ai import ApprovalCapability
+
+approvals = ApprovalCapability("https://approvals.example.com/api/aap", token)
+agent = Agent(model, tools=tools, capabilities=[approvals])
+```
+
+Every tool call the agent makes goes to the provider, including MCP and other toolset tools. A denied call returns the reason to the model as a failed tool result. Add the same capability to every agent you run as a sub-agent.
+
+Tools that run at the model provider, such as native web search or code execution, cannot be sent for approval. A run that includes one stops with an error. Use a local tool instead.
+
+To pause instead of waiting, use `ApprovalCapability(..., mode="async")` and add `DeferredToolRequests` to the agent's `output_type`. When a run ends with `DeferredToolRequests`, save `result.conversation`. Mount a `Receiver` with `resumers={"pydantic-ai": resumer(agent, load=load, save=save)}`, where `load(conversation_id)` returns the saved conversation and `save(conversation)` stores the resumed one. Calls inside a sub-agent wait instead of pausing. Continuing a conversation any other way cannot approve a call: the capability asks the provider again, and an approval with edited arguments is refused.

agentapprovalprotocol-0.1.0/README.md

@@ -0,0 +1,77 @@
+# Agent Approval Protocol for Python
+
+Put an AI agent's tool calls behind an [AAP](https://agentapprovalprotocol.io) approval provider. Each call waits for the provider's decision, runs only if approved, and runs at most once.
+
+```sh
+pip install agentapprovalprotocol
+```
+
+## Check a tool call
+
+```python
+from agentapprovalprotocol import Call, Client, Gate
+
+gate = Gate(Client("https://approvals.example.com/api/aap", token))
+
+with gate.guard(Call(key=f"{run_id}:{tool_call.id}", tool=tool_call.name, arguments=tool_call.args)) as verdict:
+    if verdict:
+        result = run_tool(tool_call)
+    else:
+        result = verdict.reason  # return this to the model as the tool result
+```
+
+`key` must identify the tool call within its run, and stay the same if the call is seen again after a retry or resume. `guard` reports whether the tool succeeded when the block exits.
+
+`AsyncGate` and `AsyncClient` provide the same API for `asyncio`.
+
+## Pause instead of waiting
+
+With `mode="async"`, `check` returns `Pending` when there is no decision yet, so the run can pause and the process can exit. Mount a `Receiver` where the provider can reach it. When a decision arrives it wakes the run, and the gate checks the decision again before anything runs.
+
+Framework integrations handle pausing and resuming for you.
+
+## LangChain, LangGraph and Deep Agents
+
+```sh
+pip install "agentapprovalprotocol[langgraph]"
+```
+
+```python
+from agentapprovalprotocol.langgraph import ApprovalMiddleware
+
+approvals = ApprovalMiddleware("https://approvals.example.com/api/aap", token)
+agent = create_agent(model, tools=tools, middleware=[approvals])
+```
+
+Every tool call the agent makes goes to the provider. A denied call returns the reason to the model as the tool result.
+
+For Deep Agents, also add the middleware to every subagent:
+
+```python
+from agentapprovalprotocol.langgraph import deep_agent_subagents
+
+agent = create_deep_agent(model, tools=tools, middleware=[approvals], subagents=deep_agent_subagents(approvals, my_subagents))
+```
+
+To pause instead of waiting, use `ApprovalMiddleware(..., mode="async")` with a checkpointer, and mount a `Receiver` with `resumers={"langgraph": resumer(agent)}`. On LangSmith Deployment, use `deployment_resumer(get_client())` in a custom route instead. Resuming a thread any other way cannot approve a call: the middleware asks the provider again.
+
+## Pydantic AI
+
+```sh
+pip install "agentapprovalprotocol[pydantic-ai]"
+```
+
+Needs Python 3.11 or later.
+
+```python
+from agentapprovalprotocol.pydantic_ai import ApprovalCapability
+
+approvals = ApprovalCapability("https://approvals.example.com/api/aap", token)
+agent = Agent(model, tools=tools, capabilities=[approvals])
+```
+
+Every tool call the agent makes goes to the provider, including MCP and other toolset tools. A denied call returns the reason to the model as a failed tool result. Add the same capability to every agent you run as a sub-agent.
+
+Tools that run at the model provider, such as native web search or code execution, cannot be sent for approval. A run that includes one stops with an error. Use a local tool instead.
+
+To pause instead of waiting, use `ApprovalCapability(..., mode="async")` and add `DeferredToolRequests` to the agent's `output_type`. When a run ends with `DeferredToolRequests`, save `result.conversation`. Mount a `Receiver` with `resumers={"pydantic-ai": resumer(agent, load=load, save=save)}`, where `load(conversation_id)` returns the saved conversation and `save(conversation)` stores the resumed one. Calls inside a sub-agent wait instead of pausing. Continuing a conversation any other way cannot approve a call: the capability asks the provider again, and an approval with edited arguments is refused.

agentapprovalprotocol-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "agentapprovalprotocol"
+version = "0.1.0"
+description = "Put an AI agent's tool calls behind an Agent Approval Protocol (AAP) approval provider."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.27"]
+keywords = ["ai", "agents", "approval", "human-in-the-loop", "aap"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://agentapprovalprotocol.io"
+Source = "https://github.com/agentapprovalprotocol/agentapprovalprotocol"
+
+[project.optional-dependencies]
+langgraph = [
+    "langchain>=1.0",
+    "langgraph>=1.0",
+]
+pydantic-ai = [
+    "pydantic-ai-slim>=2.55 ; python_full_version >= '3.11'",
+]
+
+[dependency-groups]
+dev = [
+    "deepagents>=0.7.24 ; python_full_version >= '3.11'",
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+    "pytest-timeout>=2.4.0",
+]
+
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentapprovalprotocol"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

agentapprovalprotocol-0.1.0/src/agentapprovalprotocol/__init__.py

@@ -0,0 +1,33 @@
+"""Agent Approval Protocol SDK.
+
+Put an agent's tool calls behind an AAP approval provider. ``Gate`` and
+``AsyncGate`` decide whether one call may run; framework integrations build
+on them. See https://agentapprovalprotocol.io.
+"""
+
+from ._client import AAPError, AsyncClient, Client, ConflictError, CredentialRefused, NotFound
+from ._gate import Allow, AsyncGate, Call, Deny, Gate, Pending, Verdict
+from ._wire import Consumption, Decision, Outcome, ProtocolError, Request
+from .receiver import Receiver
+
+__all__ = [
+    "AAPError",
+    "Allow",
+    "AsyncClient",
+    "AsyncGate",
+    "Call",
+    "Client",
+    "ConflictError",
+    "Consumption",
+    "CredentialRefused",
+    "Decision",
+    "Deny",
+    "Gate",
+    "NotFound",
+    "Outcome",
+    "Pending",
+    "ProtocolError",
+    "Receiver",
+    "Request",
+    "Verdict",
+]

agentapprovalprotocol-0.1.0/src/agentapprovalprotocol/_client.py

@@ -0,0 +1,201 @@
+"""AAP HTTP client, in synchronous and asynchronous forms.
+
+Both forms share the response rules below; only the transport differs.
+Transport failures, 429 and 5xx responses are retried with the same
+idempotency key until the retry budget runs out.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from email.utils import parsedate_to_datetime
+from typing import Any, Mapping
+from urllib.parse import urlsplit
+
+import httpx
+
+from ._wire import ProtocolError, Request, dumps, loads, parse_request
+
+USER_AGENT = "agentapprovalprotocol-python"
+MAX_RESPONSE = 8 << 20
+
+
+class AAPError(Exception):
+    """The operation did not produce a usable result."""
+
+
+class CredentialRefused(AAPError):
+    """The provider refused the instance credential (HTTP 401 or 403)."""
+
+
+class ConflictError(AAPError):
+    """A 409 answer, identified by the provider's error code."""
+
+    def __init__(self, code: str, message: str = ""):
+        super().__init__(f"AAP conflict: {code}")
+        self.code = code
+        self.message = message
+
+
+class NotFound(AAPError):
+    """The request is unknown or unavailable to this instance."""
+
+
+def validate_base_url(base_url: str) -> str:
+    parts = urlsplit(base_url)
+    if not parts.netloc or parts.username or parts.password or parts.query or parts.fragment:
+        raise ValueError("base URL must be an absolute AAP URL without credentials, query or fragment")
+    local = parts.hostname in ("localhost", "127.0.0.1", "::1")
+    if parts.scheme != "https" and not (parts.scheme == "http" and local):
+        raise ValueError("base URL requires HTTPS, except on localhost")
+    return base_url.rstrip("/")
+
+
+def _retry_after(response: httpx.Response) -> float | None:
+    value = response.headers.get("retry-after")
+    if value is None:
+        return None
+    if value.isdigit():
+        return float(value)
+    try:
+        return max(0.0, parsedate_to_datetime(value).timestamp() - time.time())
+    except (TypeError, ValueError):
+        return None
+
+
+def _result(response: httpx.Response, raw: bytes) -> Request | None:
+    """Turn a final response into a request, raise, or return None to retry."""
+    code = response.status_code
+    if code == 429 or code >= 500:
+        return None
+    if code in (401, 403):
+        raise CredentialRefused(f"the provider refused the instance credential (HTTP {code})")
+    if code == 404:
+        raise NotFound("the request is unavailable")
+    if code == 409:
+        try:
+            error = loads(raw)["error"]
+            raise ConflictError(str(error["code"]), str(error.get("message", "")))
+        except (ProtocolError, KeyError, TypeError) as err:
+            raise AAPError("AAP request failed (HTTP 409)") from err
+    if code not in (200, 201):
+        raise AAPError(f"AAP request failed (HTTP {code})")
+    if len(raw) > MAX_RESPONSE:
+        raise ProtocolError("AAP response too large")
+    return parse_request(loads(raw))
+
+
+class _Base:
+    def __init__(self, base_url: str, token: str, *, retry_budget: float = 30.0):
+        if not token or "\n" in token or "\r" in token:
+            raise ValueError("instance token is required and must not contain newlines")
+        self.base_url = validate_base_url(base_url)
+        self.retry_budget = retry_budget
+        self._headers = {"Authorization": f"Bearer {token}", "User-Agent": USER_AGENT}
+
+    def _request(self, method: str, path: str, body: Mapping[str, Any] | None, key: str | None) -> tuple[dict[str, str], bytes | None]:
+        headers = dict(self._headers)
+        content = None
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            content = dumps(body)
+        if key is not None:
+            headers["Idempotency-Key"] = key
+        return headers, content
+
+
+class Client(_Base):
+    """Synchronous AAP client for one instance credential."""
+
+    def __init__(self, base_url: str, token: str, *, http: httpx.Client | None = None, retry_budget: float = 30.0):
+        super().__init__(base_url, token, retry_budget=retry_budget)
+        self._http = http or httpx.Client(timeout=40.0, follow_redirects=False)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def _send(self, method: str, path: str, body: Mapping[str, Any] | None = None, key: str | None = None, *, timeout: float | None = None) -> Request:
+        headers, content = self._request(method, path, body, key)
+        deadline = time.monotonic() + self.retry_budget
+        delay = 0.1
+        while True:
+            wait = delay
+            try:
+                response = self._http.request(method, self.base_url + path, headers=headers, content=content, timeout=timeout or 40.0)
+                raw = response.read()
+                result = _result(response, raw)
+                if result is not None:
+                    return result
+                wait = max(delay, _retry_after(response) or 0.0)
+            except httpx.TransportError:
+                pass
+            if time.monotonic() + wait > deadline:
+                raise AAPError("the provider could not be reached")
+            time.sleep(wait)
+            delay = min(delay * 2, 2.0)
+
+    def create(self, submission: Mapping[str, Any], key: str) -> Request:
+        return self._send("POST", "/v1/requests", submission, key)
+
+    def get(self, request_id: str, *, wait: int | None = None) -> Request:
+        query = f"?wait={wait}s" if wait else ""
+        return self._send("GET", f"/v1/requests/{request_id}{query}", timeout=(wait or 0) + 10.0)
+
+    def cancel(self, request_id: str) -> Request:
+        return self._send("DELETE", f"/v1/requests/{request_id}")
+
+    def consume(self, request_id: str, key: str) -> Request:
+        return self._send("POST", f"/v1/requests/{request_id}/consume", None, key)
+
+    def report_outcome(self, request_id: str, status: str, note: str | None = None) -> Request:
+        body = {"status": status, **({"note": note} if note else {})}
+        return self._send("POST", f"/v1/requests/{request_id}/outcome", body)
+
+
+class AsyncClient(_Base):
+    """Asynchronous AAP client for one instance credential."""
+
+    def __init__(self, base_url: str, token: str, *, http: httpx.AsyncClient | None = None, retry_budget: float = 30.0):
+        super().__init__(base_url, token, retry_budget=retry_budget)
+        self._http = http or httpx.AsyncClient(timeout=40.0, follow_redirects=False)
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def _send(self, method: str, path: str, body: Mapping[str, Any] | None = None, key: str | None = None, *, timeout: float | None = None) -> Request:
+        headers, content = self._request(method, path, body, key)
+        deadline = time.monotonic() + self.retry_budget
+        delay = 0.1
+        while True:
+            wait = delay
+            try:
+                response = await self._http.request(method, self.base_url + path, headers=headers, content=content, timeout=timeout or 40.0)
+                raw = await response.aread()
+                result = _result(response, raw)
+                if result is not None:
+                    return result
+                wait = max(delay, _retry_after(response) or 0.0)
+            except httpx.TransportError:
+                pass
+            if time.monotonic() + wait > deadline:
+                raise AAPError("the provider could not be reached")
+            await asyncio.sleep(wait)
+            delay = min(delay * 2, 2.0)
+
+    async def create(self, submission: Mapping[str, Any], key: str) -> Request:
+        return await self._send("POST", "/v1/requests", submission, key)
+
+    async def get(self, request_id: str, *, wait: int | None = None) -> Request:
+        query = f"?wait={wait}s" if wait else ""
+        return await self._send("GET", f"/v1/requests/{request_id}{query}", timeout=(wait or 0) + 10.0)
+
+    async def cancel(self, request_id: str) -> Request:
+        return await self._send("DELETE", f"/v1/requests/{request_id}")
+
+    async def consume(self, request_id: str, key: str) -> Request:
+        return await self._send("POST", f"/v1/requests/{request_id}/consume", None, key)
+
+    async def report_outcome(self, request_id: str, status: str, note: str | None = None) -> Request:
+        body = {"status": status, **({"note": note} if note else {})}
+        return await self._send("POST", f"/v1/requests/{request_id}/outcome", body)