welt-io 0.3.2

The Strands Agents (Python) adapter for Welt's wire contract

welt-io

This project has been renamed to welt-io-strands. Install welt-io-strands and import welt_io_strands instead — this package stays published for existing installs but receives no further releases.

The Strands Agents (Python) adapter for Welt's wire contract — one of Welt's agent-side adapters.

Install

uv add welt-io

Usage

See examples/agent — the smallest complete agent built on this package (text streaming, image generation, file input, and a human-approval tool), which doubles as the example for Welt's Quick Start. The sections below explain the adapters it wires in.

API

The wire between Welt and the agent is JSON, specified by Welt's wire contract — plain Strands values do not fit it in either direction. Two functions adapt the inbound payload, three the outbound stream.

Inbound

decode_messages(messages)

Returns a copy of Welt's Converse-shaped messages with the base64-encoded file bytes restored to the raw bytes Strands expects; the input is left untouched. Its in-place predecessor, decode_file_blocks(messages), is deprecated.

decode_interrupt_responses(responses)

Turns Welt's resume payload — a mapping of interrupt id to the answer a human chose — into the interruptResponse items that Agent.stream_async resumes from.

Outbound

renderable_events(events)

Reduces raw stream_async events — not JSON-serializable as-is — to the events Welt renders:

Strands emits	On the wire	In the Slack thread
Text deltas	data	The streamed reply
Tool invocations and results	current_tool_use / tool_result	"Using tool" indicators (tool output stays off the wire)
Image / document / video blocks a tool or the model produces	file	An uploaded file (size limits)
Pending interrupts	interrupt	Buttons and/or a text field

A run that stops for human input ends its stream with one interrupt event per pending interrupt; agents that do not use interrupts see no change.

file_event(name, data)

Builds the same file event from a filename and raw bytes, for attaching arbitrary files of your own:

yield file_event("report.csv", csv_bytes)

Tool-generated files need no code at all — for example, strands-tools' generate_image returns the image as a tool-result block, which streams into the thread by itself. The example agent includes it.

interrupt_reason(message, options=..., input=...)

Builds the structured reason Welt renders as a message with the specified widgets — choice buttons (options), a free-text field (input), or both. The specs are the wire's own shapes; omitted fields keep Welt's defaults, and a typo becomes an immediate ValueError instead of a silent fallback to Welt's default rendering:

answer = tool_context.interrupt(
    "deploy-approval",
    reason=interrupt_reason(
        "Deploy to prod?",
        [
            {"value": "y", "label": "Deploy", "style": "primary"},
            {"value": "n", "label": "Cancel"},
        ],
        input={"label": "Or tell me what to do instead"},
    ),
)

Working with interrupts

Welt's Interrupts doc covers the Slack side: how each reason renders, who can answer, multiple questions, and expiry. On the Strands side:

• Prefix your interrupt names (myapp-deploy-approval). Hook-raised interrupts must be unique across the whole event, tool-raised ones within their tool — a prefix keeps both as the agent grows.
• Strands' ready-made HumanInTheLoop intervention works over Welt as-is. Its string reasons render with Welt's default Approve / Deny buttons, whose y / n values its default evaluator understands. Do not pass ask: stdio prompts and callback evaluators have no terminal on AgentCore Runtime.
• Route stdio consent prompts through interrupts instead. For strands-tools packages that gate themselves behind a stdio prompt, set BYPASS_TOOL_CONSENT=true and let HumanInTheLoop do the gating over Slack. The strands-tools handoff_to_user tool is likewise stdio-bound; a small interrupt-raising tool of your own is the replacement.

Supported Versions

Welt releases first; welt-io follows, mirroring the minor version. While both are 0.x, a welt-io 0.Y release supports Welt v0.Y — other combinations may work, but come with no guarantee.

License

MIT