agentapprovalprotocol 0.1.0__py3-none-any.whl

agentapprovalprotocol/pydantic_ai.py

@@ -0,0 +1,255 @@
+"""Approvals for Pydantic AI agents.
+
+``ApprovalCapability`` gates every function tool call an agent makes,
+including MCP and other toolset tools, with the arguments the tool will
+run with. In sync mode the call waits for the decision. In async mode the
+run ends with ``DeferredToolRequests``, you store its ``conversation``, and
+a ``Receiver`` continues it when the decision arrives. On resume the
+capability asks the provider again and ignores the approval passed in, so a
+conversation continued by anything else cannot approve a call.
+
+Install with ``pip install "agentapprovalprotocol[pydantic-ai]"``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextvars
+import inspect
+import logging
+import types
+import typing
+from dataclasses import dataclass, field
+from typing import Any, Awaitable, Callable, Literal, Mapping, Sequence
+
+from pydantic_core import to_jsonable_python
+from pydantic_ai import DeferredToolRequests, DeferredToolResults
+from pydantic_ai.capabilities import AbstractCapability, CapabilityOrdering
+from pydantic_ai.conversation import Conversation
+from pydantic_ai.exceptions import ApprovalRequired, ToolFailed, UserError
+from pydantic_ai.messages import ModelMessage, ModelResponse, TextPart, ToolCallPart
+from pydantic_ai.models import ModelRequestContext
+from pydantic_ai.tools import RunContext, ToolDefinition
+from pydantic_ai.toolsets import AbstractToolset, WrapperToolset
+from pydantic_ai.toolsets.abstract import ToolsetTool
+
+from ._client import AsyncClient
+from ._gate import FAIL_CLOSED, AsyncGate, Call, Deny, Pending
+from ._wire import Request
+
+log = logging.getLogger("agentapprovalprotocol")
+
+FRAMEWORK = "pydantic-ai"
+METADATA_KEY = "aap_request_id"
+EDITED = "An approved call cannot run with edited arguments. The call was not run."
+# Native tool search only finds tools among the agent's own, which are gated.
+SEARCH_ONLY = frozenset({"tool_search"})
+
+# Set while a gated tool runs. An agent run started inside that tool (a
+# sub-agent) cannot pause: its caller would get the pause as a tool result.
+_in_tool: contextvars.ContextVar[bool] = contextvars.ContextVar("aap_pydantic_ai_in_tool", default=False)
+
+
+def _allows_deferred(spec: Any) -> bool:
+    """Whether an agent's output type includes ``DeferredToolRequests``."""
+    if spec is DeferredToolRequests:
+        return True
+    if isinstance(spec, (list, tuple)):
+        return any(_allows_deferred(item) for item in spec)
+    if typing.get_origin(spec) in (typing.Union, types.UnionType):
+        return any(_allows_deferred(item) for item in typing.get_args(spec))
+    return False
+
+
+def _response_with(messages: Sequence[ModelMessage], tool_call_id: str) -> tuple[ModelResponse, ToolCallPart] | None:
+    for message in reversed(messages):
+        if isinstance(message, ModelResponse):
+            for part in message.parts:
+                if isinstance(part, ToolCallPart) and part.tool_call_id == tool_call_id:
+                    return message, part
+    return None
+
+
+def _reasoning(response: ModelResponse | None) -> str | None:
+    if response is None:
+        return None
+    text = "\n".join(part.content for part in response.parts if isinstance(part, TextPart)).strip()
+    return text or None
+
+
+@dataclass(init=False)
+class ApprovalCapability(AbstractCapability[Any]):
+    """Send every tool call to an AAP provider before it runs.
+
+    Add it to the agent's ``capabilities`` and to every agent that runs as
+    a sub-agent. Provider-run (native) tools cannot be gated, so a model
+    request that includes one is refused.
+
+    ``mode="async"`` pauses only when the agent's ``output_type`` includes
+    ``DeferredToolRequests``; otherwise, and inside a sub-agent, calls wait.
+    """
+
+    gate: AsyncGate = field(repr=False)
+    context: dict[str, Any] = field(default_factory=dict)
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        token: str | None = None,
+        *,
+        mode: Literal["sync", "async"] = "sync",
+        gate: AsyncGate | None = None,
+        context: Mapping[str, Any] | None = None,
+        **gate_options: Any,
+    ):
+        if gate is None:
+            if base_url is None or token is None:
+                raise ValueError("pass base_url and token, or a gate")
+            gate = AsyncGate(AsyncClient(base_url, token), mode=mode, **gate_options)
+        self.gate = gate
+        self.context = {"framework": FRAMEWORK, **(context or {})}
+
+    @classmethod
+    def get_serialization_name(cls) -> str | None:
+        return None
+
+    def get_ordering(self) -> CapabilityOrdering:
+        # Outermost, so tools other capabilities add around the agent's own
+        # (a search or code tool, say) are gated too.
+        return CapabilityOrdering(position="outermost")
+
+    def get_wrapper_toolset(self, toolset: AbstractToolset[Any]) -> AbstractToolset[Any]:
+        return _GatedToolset(toolset, approvals=self)
+
+    async def before_model_request(self, ctx: RunContext[Any], request_context: ModelRequestContext) -> ModelRequestContext:
+        kinds = {getattr(tool, "kind", type(tool).__name__) for tool in request_context.model_request_parameters.native_tools} - SEARCH_ONLY
+        if kinds:
+            raise UserError(f"Native tools run at the model provider and cannot be sent for approval: {', '.join(sorted(kinds))}. Remove them, or use a local tool instead.")
+        return request_context
+
+    async def after_tool_validate(self, ctx: RunContext[Any], *, call: ToolCallPart, tool_def: ToolDefinition, args: dict[str, Any]) -> dict[str, Any]:
+        # ToolApproved(override_args=...) replaces the call's arguments. An
+        # approval covers the arguments it was given, so refuse the edit.
+        if ctx.tool_call_approved:
+            found = _response_with(ctx.messages, call.tool_call_id)
+            if found is not None and found[1].args_as_dict() != call.args_as_dict():
+                raise ToolFailed(EDITED)
+        return args
+
+    def _call(self, name: str, args: dict[str, Any], ctx: RunContext[Any]) -> tuple[Call, bool]:
+        conversation = ctx.conversation_id
+        tool_call_id = ctx.tool_call_id or "-"
+        found = _response_with(ctx.messages, tool_call_id)
+        resume = None
+        if conversation is not None:
+            resume = {"framework": FRAMEWORK, "conversation_id": conversation}
+        call = Call(
+            key=f"{conversation or '-'}:{tool_call_id}",
+            tool=name,
+            arguments=to_jsonable_python(args),
+            reasoning=_reasoning(found[0] if found else None),
+            context=self.context,
+            resume=resume,
+        )
+        can_pause = (
+            conversation is not None
+            and ctx.tool_call_id is not None
+            and not _in_tool.get()
+            and ctx.agent is not None
+            and _allows_deferred(ctx.agent.output_type)
+        )
+        return call, can_pause
+
+
+@dataclass
+class _GatedToolset(WrapperToolset[Any]):
+    """Checks each call with the gate, at the point the tool runs."""
+
+    approvals: ApprovalCapability = field(kw_only=True)
+
+    async def call_tool(self, name: str, tool_args: dict[str, Any], ctx: RunContext[Any], tool: ToolsetTool[Any]) -> Any:
+        gate = self.approvals.gate
+        try:
+            call, can_pause = self.approvals._call(name, tool_args, ctx)
+        except Exception:  # noqa: BLE001 - arguments that cannot be sent are not run
+            log.exception("could not build the approval request for %s", name)
+            raise ToolFailed(FAIL_CLOSED) from None
+        verdict = await gate.check(call, can_pause=can_pause)
+        if isinstance(verdict, Pending):
+            # The run ends with DeferredToolRequests. Any approval passed back
+            # on resume is ignored: this check runs again and asks the provider.
+            raise ApprovalRequired(metadata={METADATA_KEY: verdict.request_id})
+        if isinstance(verdict, Deny):
+            raise ToolFailed(verdict.reason)
+        token = _in_tool.set(True)
+        try:
+            result = await self.wrapped.call_tool(name, tool_args, ctx, tool)
+        except BaseException:
+            if gate.report_outcomes:
+                await verdict.report("failed")
+            raise
+        finally:
+            _in_tool.reset(token)
+        if gate.report_outcomes:
+            await verdict.report("succeeded")
+        return result
+
+
+def pending_request_ids(requests: DeferredToolRequests | None) -> dict[str, str]:
+    """The AAP request each paused call waits on, keyed by tool call ID."""
+    if requests is None:
+        return {}
+    out = {}
+    for call in requests.approvals:
+        request_id = (requests.metadata.get(call.tool_call_id) or {}).get(METADATA_KEY)
+        if isinstance(request_id, str):
+            out[call.tool_call_id] = request_id
+    return out
+
+
+async def _maybe(value: Any) -> Any:
+    return await value if inspect.isawaitable(value) else value
+
+
+def resumer(
+    agent: Any,
+    *,
+    load: Callable[[str], Conversation | None | Awaitable[Conversation | None]],
+    save: Callable[[Conversation], Any],
+    **run_options: Any,
+) -> Callable[[Mapping[str, Any], Request], Awaitable[None]]:
+    """A ``Receiver`` resumer that continues a stored conversation.
+
+    ``load(conversation_id)`` returns the ``Conversation`` you saved when the
+    run paused, or ``None``. The resumed run's conversation is passed to
+    ``save``. Either may be async. ``run_options`` (``deps``, for example)
+    are passed to ``agent.run``.
+
+    A conversation is continued only while it waits on the decided request,
+    one resume per conversation at a time in this process. Every paused
+    approval in it is answered, and each is checked with the provider again:
+    calls still undecided pause again.
+    """
+    locks: dict[str, asyncio.Lock] = {}
+
+    async def resume(handle: Mapping[str, Any], request: Request) -> None:
+        conversation_id = handle.get("conversation_id")
+        if not isinstance(conversation_id, str):
+            return
+        async with locks.setdefault(conversation_id, asyncio.Lock()):
+            conversation = await _maybe(load(conversation_id))
+            if conversation is None:
+                return
+            waiting = conversation.deferred_tool_requests
+            ids = pending_request_ids(waiting)
+            if request.id not in ids.values():
+                return
+            assert waiting is not None
+            if waiting.calls or len(ids) != len(waiting.approvals):
+                log.warning("conversation %s also waits on calls that are not AAP approvals; resume it yourself", conversation_id)
+                return
+            results = DeferredToolResults(approvals={tool_call_id: True for tool_call_id in ids})
+            result = await agent.run(conversation=conversation, deferred_tool_results=results, **run_options)
+            await _maybe(save(result.conversation))
+
+    return resume

agentapprovalprotocol/receiver.py

@@ -0,0 +1,168 @@
+"""Webhook receiver for asynchronous mode.
+
+The receiver verifies AAP webhooks, answers receiver verification during
+provisioning, and wakes paused runs. A notification only wakes a run: the
+gate fetches and consumes the decision itself, so the receiver keeps no
+state and a repeated or forged event at most wakes a run that pauses again.
+
+The resume handle is read from the request's ``context.resume``, which the
+gate wrote when it created the request. Its ``framework`` names the resumer
+to call.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import hashlib
+import hmac
+import inspect
+import json
+import logging
+import time
+from typing import Any, Awaitable, Callable, Mapping
+
+from ._client import AAPError, AsyncClient
+from ._wire import ProtocolError, Request, loads
+
+log = logging.getLogger("agentapprovalprotocol")
+
+Resumer = Callable[[Mapping[str, Any], Request], Awaitable[None] | None]
+
+
+def signing_key(secret: str) -> bytes:
+    if not secret.startswith("whsec_"):
+        raise ValueError("signing secret must start with whsec_")
+    return base64.b64decode(secret[len("whsec_") :], validate=True)
+
+
+def sign(secret: str, message_id: str, timestamp: int, body: bytes) -> str:
+    """The ``webhook-signature`` header value for one delivery attempt."""
+    digest = hmac.new(signing_key(secret), f"{message_id}.{timestamp}.".encode() + body, hashlib.sha256).digest()
+    return "v1," + base64.b64encode(digest).decode()
+
+
+def verify(secret: str, headers: Mapping[str, str], body: bytes, *, tolerance: int = 300, now: float | None = None) -> dict[str, Any]:
+    """Verify a delivery and return its parsed body. Raises ``ValueError``."""
+    lower = {k.lower(): v for k, v in headers.items()}
+    message_id = lower.get("webhook-id", "")
+    stamp = lower.get("webhook-timestamp", "")
+    signatures = lower.get("webhook-signature", "").split()
+    if not message_id or not stamp.isdigit() or not signatures:
+        raise ValueError("missing webhook headers")
+    if abs((now if now is not None else time.time()) - int(stamp)) > tolerance:
+        raise ValueError("webhook timestamp outside tolerance")
+    expected = sign(secret, message_id, int(stamp), body)
+    if not any(hmac.compare_digest(expected, candidate) for candidate in signatures if candidate.startswith("v1,")):
+        raise ValueError("invalid webhook signature")
+    try:
+        message = loads(body)
+    except ProtocolError as err:
+        raise ValueError("invalid webhook body") from err
+    if not isinstance(message, dict) or message.get("id") != message_id:
+        raise ValueError("webhook ID does not match the body")
+    return message
+
+
+class Receiver:
+    """Verifies AAP webhooks and wakes paused runs.
+
+    ``registration_id`` is the ID the provisioner generated for this
+    receiver; verification messages for any other registration are refused.
+    ``instance_id``, once known, restricts notifications to that instance.
+    ``resumers`` maps a framework name to a function that resumes a run from
+    its resume handle.
+    """
+
+    def __init__(
+        self,
+        *,
+        secret: str,
+        client: AsyncClient,
+        resumers: Mapping[str, Resumer],
+        registration_id: str | None = None,
+        instance_id: str | None = None,
+        tolerance: int = 300,
+    ):
+        signing_key(secret)
+        self.secret = secret
+        self.client = client
+        self.resumers = dict(resumers)
+        self.registration_id = registration_id
+        self.instance_id = instance_id
+        self.tolerance = tolerance
+        self._tasks: set[asyncio.Task[None]] = set()
+
+    async def handle(self, headers: Mapping[str, str], body: bytes) -> tuple[int, bytes]:
+        """Process one delivery. Returns the HTTP status and body to send.
+
+        A notification is acknowledged at once and the run is woken in the
+        background, because a delivery attempt has a ten second limit.
+        """
+        try:
+            message = verify(self.secret, headers, body, tolerance=self.tolerance)
+        except ValueError:
+            return 401, b""
+        kind = message.get("type")
+        if kind == "webhook.verification":
+            if self.registration_id is None or message.get("registration_id") != self.registration_id or not isinstance(message.get("challenge"), str):
+                return 403, b""
+            return 200, json.dumps({"challenge": message["challenge"]}).encode()
+        if kind == "request.resolved":
+            if self.instance_id is not None and message.get("instance_id") != self.instance_id:
+                return 403, b""
+            request_id = message.get("request_id")
+            if isinstance(request_id, str):
+                task = asyncio.ensure_future(self.wake(request_id))
+                self._tasks.add(task)
+                task.add_done_callback(self._tasks.discard)
+            return 204, b""
+        return 400, b""
+
+    async def wake(self, request_id: str) -> bool:
+        """Resume the run waiting on a request. Also the recovery sweep's entry point."""
+        try:
+            request = await self.client.get(request_id)
+        except (AAPError, ProtocolError):
+            log.warning("could not read request %s to resume it", request_id, exc_info=True)
+            return False
+        handle = (request.context or {}).get("resume")
+        resumer = self.resumers.get(handle.get("framework", "")) if isinstance(handle, dict) else None
+        if resumer is None:
+            log.warning("request %s has no resume handle this receiver can use", request_id)
+            return False
+        try:
+            result = resumer(handle, request)
+            if inspect.isawaitable(result):
+                await result
+            return True
+        except Exception:  # noqa: BLE001 - a failed resume must not crash the receiver
+            log.exception("resuming the run for request %s failed", request_id)
+            return False
+
+    def asgi(self) -> Callable[..., Awaitable[None]]:
+        """An ASGI app that accepts POSTed webhooks at any path it is mounted on."""
+
+        async def app(scope: dict[str, Any], receive: Callable[[], Awaitable[dict[str, Any]]], send: Callable[[dict[str, Any]], Awaitable[None]]) -> None:
+            if scope["type"] != "http":
+                return
+            if scope["method"] != "POST":
+                await _respond(send, 405, b"")
+                return
+            chunks = []
+            more = True
+            while more:
+                event = await receive()
+                chunks.append(event.get("body", b""))
+                more = event.get("more_body", False)
+            headers = {k.decode("latin-1"): v.decode("latin-1") for k, v in scope.get("headers", [])}
+            status, body = await self.handle(headers, b"".join(chunks))
+            await _respond(send, status, body)
+
+        return app
+
+
+async def _respond(send: Callable[[dict[str, Any]], Awaitable[None]], status: int, body: bytes) -> None:
+    headers = [(b"content-type", b"application/json")] if body else []
+    await send({"type": "http.response.start", "status": status, "headers": headers})
+    await send({"type": "http.response.body", "body": body})

agentapprovalprotocol/testing.py

@@ -0,0 +1,173 @@
+"""An in-memory AAP provider for tests.
+
+``FakeProvider`` implements the AAP request operations, including consume
+and outcome, as an httpx transport, so ``Client`` and ``AsyncClient`` talk
+to it without a network. Framework shims run the conformance scenarios in
+their own tests against it.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+import time
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from typing import Any, Callable
+
+import httpx
+
+from ._client import AsyncClient, Client
+from .receiver import sign
+
+BASE_URL = "https://provider.test/aap"
+TOKEN = "test-token"
+SECRET = "whsec_AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8="
+
+
+def _stamp(at: datetime) -> str:
+    return at.strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+
+
+@dataclass
+class Stored:
+    body: dict[str, Any]
+    id: str
+    created_at: datetime
+    deadline_at: datetime
+    status: str = "pending"
+    note: str | None = None
+    decided_at: datetime | None = None
+    expires_at: datetime | None = None
+    consumed_key: str | None = None
+    consumed_at: datetime | None = None
+    outcome: dict[str, Any] | None = None
+
+    def wire(self) -> dict[str, Any]:
+        out: dict[str, Any] = {**self.body, "id": self.id, "status": self.status, "created_at": _stamp(self.created_at), "deadline_at": _stamp(self.deadline_at)}
+        if self.decided_at:
+            decision: dict[str, Any] = {"status": self.status, "decided_at": _stamp(self.decided_at)}
+            if self.note:
+                decision["note"] = self.note
+            if self.expires_at:
+                decision["expires_at"] = _stamp(self.expires_at)
+            out["decision"] = decision
+        if self.consumed_at:
+            out["consumption"] = {"consumed_at": _stamp(self.consumed_at), **({"outcome": self.outcome} if self.outcome else {})}
+        return out
+
+
+@dataclass
+class FakeProvider:
+    """In-memory provider. ``auto`` decides each new request at once."""
+
+    auto: str | None = "approved"
+    validity: timedelta = timedelta(minutes=5)
+    requests: dict[str, Stored] = field(default_factory=dict)
+    keys: dict[str, str] = field(default_factory=dict)
+    calls: list[tuple[str, str]] = field(default_factory=list)
+    #: Optional hook to replace a response: return an httpx.Response to use it.
+    intercept: Callable[[httpx.Request], httpx.Response | None] | None = None
+
+    def __post_init__(self) -> None:
+        self._lock = threading.Lock()
+
+    # Test controls
+
+    def decide(self, request_id: str, status: str = "approved", note: str | None = None) -> None:
+        with self._lock:
+            self._decide(self.requests[request_id], status, note)
+
+    def only(self) -> Stored:
+        (stored,) = self.requests.values()
+        return stored
+
+    def client(self, **kwargs: Any) -> Client:
+        return Client(BASE_URL, TOKEN, http=httpx.Client(transport=httpx.MockTransport(self.handle)), **kwargs)
+
+    def async_client(self, **kwargs: Any) -> AsyncClient:
+        return AsyncClient(BASE_URL, TOKEN, http=httpx.AsyncClient(transport=httpx.MockTransport(self.handle)), **kwargs)
+
+    def webhook(self, request_id: str, *, instance_id: str = "b29a43a7-1949-4b9f-9d61-b7ae66f85d31", secret: str = SECRET) -> tuple[dict[str, str], bytes]:
+        """Headers and body of a signed request.resolved notification."""
+        event_id = str(uuid.uuid4())
+        body = json.dumps({"id": event_id, "type": "request.resolved", "instance_id": instance_id, "request_id": request_id, "created_at": _stamp(datetime.now(timezone.utc))}).encode()
+        stamp = int(time.time())
+        return {"webhook-id": event_id, "webhook-timestamp": str(stamp), "webhook-signature": sign(secret, event_id, stamp, body)}, body
+
+    # Transport
+
+    def _decide(self, stored: Stored, status: str, note: str | None) -> None:
+        if stored.status != "pending":
+            return
+        now = datetime.now(timezone.utc)
+        stored.status, stored.note, stored.decided_at = status, note, now
+        stored.expires_at = now + self.validity if status == "approved" else None
+
+    def handle(self, request: httpx.Request) -> httpx.Response:
+        if self.intercept and (replaced := self.intercept(request)) is not None:
+            return replaced
+        with self._lock:
+            return self._handle(request)
+
+    def _handle(self, request: httpx.Request) -> httpx.Response:
+        if request.headers.get("authorization") != f"Bearer {TOKEN}":
+            return httpx.Response(401)
+        path = request.url.path.removeprefix("/aap/v1/requests")
+        self.calls.append((request.method, path or "/"))
+        key = request.headers.get("idempotency-key")
+        if request.method == "POST" and path == "":
+            if not key:
+                return _error(400, "invalid_request", "missing_idempotency_key")
+            body = json.loads(request.content)
+            if key in self.keys:
+                stored = self.requests[self.keys[key]]
+                if json.dumps(stored.body, sort_keys=True, default=str) != json.dumps(body, sort_keys=True, default=str):
+                    return _error(409, "conflict", "idempotency_conflict")
+                return httpx.Response(200, json=stored.wire())
+            now = datetime.now(timezone.utc)
+            stored = Stored(body=body, id=str(uuid.uuid4()), created_at=now, deadline_at=now + timedelta(minutes=30))
+            self.requests[stored.id] = stored
+            self.keys[key] = stored.id
+            if self.auto:
+                self._decide(stored, self.auto, None)
+            return httpx.Response(201, json=stored.wire())
+        parts = path.strip("/").split("/")
+        stored = self.requests.get(parts[0])
+        if stored is None:
+            return _error(404, "not_found", "not_found")
+        if request.method == "GET" and len(parts) == 1:
+            return httpx.Response(200, json=stored.wire())
+        if request.method == "DELETE" and len(parts) == 1:
+            if stored.status != "pending" and stored.status != "cancelled":
+                return _error(409, "conflict", "already_terminal")
+            self._decide(stored, "cancelled", None)
+            return httpx.Response(200, json=stored.wire())
+        if request.method == "POST" and parts[1:] == ["consume"]:
+            if not key:
+                return _error(400, "invalid_request", "missing_idempotency_key")
+            if stored.consumed_key == key:
+                return httpx.Response(200, json=stored.wire())
+            if stored.consumed_key is not None:
+                return _error(409, "conflict", "already_consumed")
+            if stored.status != "approved":
+                return _error(409, "conflict", "not_approved")
+            if stored.expires_at is None or datetime.now(timezone.utc) >= stored.expires_at:
+                return _error(409, "conflict", "approval_expired")
+            stored.consumed_key, stored.consumed_at = key, datetime.now(timezone.utc)
+            return httpx.Response(200, json=stored.wire())
+        if request.method == "POST" and parts[1:] == ["outcome"]:
+            report = json.loads(request.content)
+            if stored.consumed_at is None:
+                return _error(409, "conflict", "not_consumed")
+            if stored.outcome is not None:
+                same = stored.outcome["status"] == report.get("status") and stored.outcome.get("note") == report.get("note")
+                return httpx.Response(200, json=stored.wire()) if same else _error(409, "conflict", "outcome_conflict")
+            stored.outcome = {**report, "reported_at": _stamp(datetime.now(timezone.utc))}
+            return httpx.Response(200, json=stored.wire())
+        return httpx.Response(405)
+
+
+def _error(status: int, kind: str, code: str) -> httpx.Response:
+    return httpx.Response(status, json={"error": {"type": kind, "code": code, "message": code, "request_id": str(uuid.uuid4())}})