Metadata-Version: 2.5
Name: agentmux-sdk
Version: 0.1.4
Summary: Official Python SDK for the AgentMux control plane (health, invocations, management, bootstrap).
Project-URL: Homepage, https://github.com/wangning19940904/AgentMux
Project-URL: Documentation, https://github.com/wangning19940904/AgentMux/blob/main/contract/CONTRACT.md
Author: AgentMux
License-Expression: MIT
Keywords: agentmux,agents,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27
Description-Content-Type: text/markdown

# agentmux-sdk

Official Python SDK for [AgentMux](https://github.com/wangning19940904/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`.

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

## Health handshake

```python
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

```python
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

```python
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

```python
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)

```bash
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`](https://github.com/wangning19940904/AgentMux/blob/main/contract/CONTRACT.md).
