agentmux-sdk

Official Python SDK for AgentMux: health/capability discovery, direct Agent invocation (sync + SSE streaming), management resources, Console session embedding and a bootstrap installer.

The PyPI name agentmux belongs to an unrelated project, so this package is agentmux-sdk and imports as agentmux_sdk.

pip install agentmux-sdk    # or: uv add agentmux-sdk

Health handshake

from agentmux_sdk import AgentMuxClient

client = AgentMuxClient(
    base_url="http://127.0.0.1:8765",
    token="<bridge token>",           # optional when bridge auth is disabled
    min_version="v0.1.3",             # optional consumer floor
)

report = client.health()
# report.state: ready | unauthorized | incompatible | unreachable | missing
print(report.state, report.version, report.contract_version)

Run an Agent

result = client.invoke(agent_id="agent-abc", input="summarize today's spending")
print(result.answer)

for event in client.invoke_stream(agent_id="agent-abc", input="analyze this portfolio"):
    if event.type in ("output", "thinking"):
        render(event.text)   # full snapshot: replace previous text, don't append
    elif event.type == "completed":
        print(event.result.answer)

An async twin (AsyncAgentMuxClient) offers the same API with await / async for.

Management resources

client.agents.list()
client.channels.list()
client.triggers.run("trigger-id")
client.orchestrations.create([{"id": "t1", "input": "..."}])
client.usage(period="daily")
client.send(project="myproj", text="deploy finished")

Embed the Console

session = client.console.create_session()
# Redirect the user's browser to session.enter_url (valid ~60s, single use).
# It sets an HttpOnly cookie and lands on the Console.

Install / upgrade AgentMux (bootstrap)

python -m agentmux_sdk.bootstrap --mode local --version v0.1.4
sudo AGENTMUX_BRIDGE_TOKEN=... python -m agentmux_sdk.bootstrap --mode production --version v0.1.4

Downloads are verified against the GoReleaser checksums.txt; installs use an atomic current symlink switch with automatic rollback on failed health checks.

Contract

This SDK speaks contract major 1 as defined in contract/CONTRACT.md.