Handlers¶
Run tool calls from queue messages, serverless events and pipelines.
Handlers: run tool calls from queue messages, serverless events and pipelines.
MAX_ENVELOPE_BYTES = 1 << 20
module-attribute
¶
Reply = dict[str, Any]
module-attribute
¶
Envelope
dataclass
¶
A parsed envelope: a call (tool set) or a resume (approval_id set).
is_resume
property
¶
True when this envelope resumes a decided approval.
RunSync
¶
A Runner with one fresh event loop per invocation (run_sync); nothing stays warm.
run(work, *, timeout=None)
¶
Run work() on a fresh loop.
Runner
¶
Bases: Protocol
Runs async work from sync code: a shared LoopRunner by default, or RunSync.
run(work, *, timeout=None)
¶
Run work() to completion; TimeoutError past timeout seconds.
handle_envelope(executor, payload, *, tools=None, message_id='', source='')
async
¶
Run one call (or resume one decided approval) and return a JSON-safe reply.
Replies: {"status": "ok", "result", ...}, {"status": "pending_approval",
"approval_id", ...} or, for a redelivered resume whose decision was already used,
{"status": "already_done", "approval_id", ...}; all with tool, run_id, call_id.
message_id (the source's delivery id, stable across redeliveries) names the call when
the envelope has no ids; source keeps ids of different sources apart. tools limits
what runs.
Raises:
| Type | Description |
|---|---|
ToolUsageError
|
a malformed envelope, or a call or resume of an approval the HTTP tool server (or a flow) owns. |
ToolNotFound
|
the tool is unknown or not in |
ApprovalNotFound
|
a resume of a missing approval. |
AdapterError
|
any other failure of the call (ApprovalDenied, ToolFailed, ...). |
parse_envelope(payload, *, message_id='', source='')
¶
Validate payload; a call without ids gets ids derived from message_id, else fresh.
A redelivered message keeps its message_id, so derived ids name the same call again.
Decisions never travel in an envelope: only an ApprovalStore holds them.
Raises:
| Type | Description |
|---|---|
ToolUsageError
|
not a JSON object, too large, unknown or missing keys, bad values. |
tool_handler(executor, *, tools=None, timeout=60.0, margin_s=1.0, runner=None)
¶
A sync handler(event, context=None) that runs envelopes through executor.
Events: an SQS batch (Records, returns {"batchItemFailures": [...]}), an
EventBridge event (the envelope in detail), or the envelope itself (direct invoke,
other hosts). Each invocation gets min(timeout, remaining time - margin_s) seconds
when context has get_remaining_time_in_millis(). Without runner, handlers share
the process's sync loop (the one run_sync uses), so warm invocations reuse
LoopLocal clients. A direct invoke takes its delivery id from context.aws_request_id,
which Lambda keeps across async retries.
Raises:
| Type | Description |
|---|---|
ToolUsageError
|
|