fix(sdk): use ephemeral ports for Parlant servers

[darvell-thenvoi]

What changed

All five Parlant examples (01_basic_agent.py–05_jerry_agent.py) now start their in-process servers on ports reserved from the OS instead of Parlant's fixed defaults:

ports = reserve_server_ports()
async with p.Server(
    port=ports.port,
    tool_service_port=ports.tool_service_port,
    nlp_service=p.NLPServices.openai,
) as server:
    ...

reserve_server_ports() is new, in src/band/integrations/parlant/ports.py. The baseline E2E toolkit already had this logic privately as parlant_server.py::_reserve_two_ports; it's lifted into the SDK so the examples (which can't import from tests/) and the toolkit share one definition, and the toolkit now imports it.

The README gains a "Running two agents locally (Tom and Jerry)" section.

Why

Parlant's integrated tool service binds a fixed default port (8818) during Server.__aenter__. Starting a second Parlant agent on the same machine fails while the first holds it — running Tom and Jerry side by side, the second dies with SystemExit: 1 out of uvicorn startup.

Why not port=0? Parlant doesn't support it: it string-formats the number it's given into URLs rather than reading it back off the bound socket. At the pinned v3.3.2:

• tool_service_port=0 — the built-in tool service registers as url=f"http://{host}:{port}" → http://127.0.0.1:0, and kind == "sdk" resolves to an HTTP PluginClient. Every @p.tool is routed there, so tool calls dial port 0 — including band_send_message, i.e. the agent can't reply at all.
• port=0 — the readiness poll targets http://localhost:0/healthz and swallows ConnectError in a 1s retry loop, so ready never sets and finally: await health_check_task never returns. Ctrl-C hangs.

Reserving instead: bind two sockets at once (so the OS can't return the same port twice), read the assigned numbers, close them, and hand Parlant real integers to re-bind. The close→rebind gap is the standard ephemeral-port reservation race — far smaller than the collision risk of two fixed ports.

Validation

Static:

uv run ruff check . && uv run ruff format --check .
uv run pyrefly check
uv run pytest tests/ --ignore=tests/integration/ --ignore=tests/e2e/   # 4071 passed, 81 skipped

Behavioural — asserted against Parlant's own ServiceRegistry that the reserved port reaches the registered URL:

RESERVED   -> port=49751 tool_service_port=49752
REGISTERED -> http://127.0.0.1:49752          # not :0
CONNECTED  -> tool service is live on 49752
GET http://localhost:49751/healthz "HTTP/1.1 200 OK"

That health check is the exact call port=0 left retrying forever; shutdown returned cleanly rather than hanging.

End-to-end — Tom and Jerry run concurrently against the live platform, on distinct pairs (49791/49792 and 49801/49802), holding a real conversation. 92 and 80 tool-path sends respectively, zero connection errors:

Jerry: Quadruple-layer soufflé, @tom? Now you're speaking my language…
Tom: Keep those whiskers twitching, @jerry—

band_send_message over HTTP to the plugin server is precisely what tool_service_port=0 would have broken.

Notes

Rebased onto current main, squashed to one commit.

Earlier revisions of this branch carried a large Parlant rewrite plus generic-runner/docs changes; those either landed on main independently or were superseded, so this is scoped to the port fix alone.

The opentelemetry-resourcedetector-gcp commit has been dropped. It's no longer needed on two counts: main already declares that dependency (landed independently after this branch's base), and upstream has since published a stable 1.14.0 after the yanked 1.13.0, so a fresh lockfile-free resolve of [dev]/[google_adk] succeeds without any declaration. Verified by building a wheel with the declaration removed and dry-running [dev] in a clean venv — resolves to stable 1.14.0. The packaging CI job passes on this branch, which carries neither fix.

Closes INT-530

[linear]

INT-530

[AlexanderZ-Band]

Dep commit looks right (one wording fix inline). The Parlant half needs rework: port=0 / tool_service_port=0 aren't supported by Parlant — it formats the port into URLs instead of reading the bound socket, so tool calls dial port 0 and shutdown hangs. Details inline. The dep commit is fine on its own — worth splitting it out so it can land now and unblock the packaging job.

[AlexanderZ-Band]

port=0 isn't supported by Parlant — it string-formats the port into URLs and never reads it back from the bound socket (all refs at our pinned v3.3.2):

• tool_service_port=0: the built-in tool service registers as url=f"http://{host}:{port}" → http://127.0.0.1:0, and kind == "sdk" resolves to an HTTP PluginClient. Every @p.tool is routed to that service, so tool calls dial port 0.
• port=0: the readiness poll targets http://localhost:0/healthz and swallows ConnectError in a 1s retry loop, so ready never sets and finally: await health_check_task never returns — Ctrl-C hangs.

The mechanism already exists: tests/e2e/baseline/toolkit/parlant_server.py::_reserve_two_ports reserves two real ephemeral ports, closes them, and passes the integers — "which Parlant re-binds itself". Suggest lifting it into src/band/integrations/parlant/ (examples can't import from tests/) so examples and the baseline toolkit share one definition, and logging the chosen ports — the fixed 8800 UI is otherwise unreachable.

[AlexanderZ-Band]

Concrete fallout of tool_service_port=0 here: the guideline below attaches parlant_tools and tells Tom to reply with band_send_message, but that call goes over HTTP to the built-in tool service registered at http://127.0.0.1:0. Tom can't reply at all — worth running Tom+Jerry through one actual reply before merging.

[AlexanderZ-Band]

This documents behaviour that doesn't hold: with tool_service_port=0 the two-agent run starts fine and then dies at the first tool call (see the note on 01_basic_agent.py). Needs updating once the ports come from a real reservation.

[AlexanderZ-Band]

Two things on this line.

The floor is inert — only the a0 suffix does work (it satisfies uv's pre-release opt-in). Verified with uv pip install --dry-run "<wheel>[extra]" against a probe package:

>=1.0a0      -> resourcedetector-gcp==1.12.0a0
>=1.5.0a0    -> resourcedetector-gcp==1.12.0a0
>=1.11.0a0   -> resourcedetector-gcp==1.12.0a0

1.11.0a0 is tighter than anything upstream asks (opentelemetry-exporter-gcp-trace wants ==1.*,>=1.5.0dev0; google-adk wants >=1.9.0a0,<2), so it buys nothing and adds a future conflict surface. Prefer mirroring upstream: >=1.5.0a0.

Don't let anyone "fix" this by excluding the yank instead. With [tool.uv] constraint-dependencies = ["opentelemetry-resourcedetector-gcp!=1.13.0"], uv silently backtracks opentelemetry-exporter-gcp-trace to 1.4.0 rather than erroring — a wrong resolution with no signal. Declaring it here, as you did, is the only fix that travels with the published package.

The comment above needs rewording — it points the next reader at the wrong resolver. pip already resolves this: pip install --dry-run "google-adk>=1.0.0,<2" picks opentelemetry-resourcedetector-gcp-1.12.0a0, because PEP 440 permits pre-releases when the specifier itself carries one and google-adk requests >=1.9.0a0. The failure is uv-specific: uv accepts pre-releases only for a direct dependency with a pre-release specifier, or when all published versions are pre-releases — and the yanked stable 1.13.0 ("breaks imports") defeats that second rule.