Metadata-Version: 2.4
Name: agentforge-agentrelay
Version: 0.1.0
Summary: Official Python client and CLI for the hosted AgentRelay service
Author: AgentForge Labs
License-Expression: AGPL-3.0-only
Project-URL: Homepage, https://relay.web-tasarimci.com
Project-URL: Documentation, https://relay.web-tasarimci.com/docs
Project-URL: Self-hosted Community gateway, https://pypi.org/project/agentforge-telegram-gateway/
Keywords: agentrelay,hosted,notifications,mcp,agentforge
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Dynamic: license-file

# AgentRelay hosted Python SDK and CLI

`agentforge-agentrelay` connects to the AgentForge-managed AgentRelay HTTPS service. You need an AgentRelay account and API key, or you can sign in from the CLI. Hosted calls use workspace and agent IDs; Telegram bot tokens and chat IDs stay in the managed connection configuration.

The separate [`agentforge-telegram-gateway`](https://pypi.org/project/agentforge-telegram-gateway/) package is the self-hosted Community gateway. It remains account-free, locally hosted, and compatible with its existing CLI/API. Installing this hosted client does not replace or alter that package.

```bash
python -m pip install agentforge-agentrelay
agentrelay auth login
agentrelay auth status
agentrelay send WORKSPACE_ID AGENT_ID "Hello from AgentRelay"
```

For servers and CI, set `AGENTRELAY_API_KEY` or `AGENTRELAY_API_KEY_FILE` to a private file and run the same commands. The CLI never opens a browser in headless mode. `agentrelay auth logout` removes stored OAuth credentials. SDK use is explicit and never opens a browser:

```python
import os
from agentrelay_core import AgentRelayClient

relay = AgentRelayClient(api_key=os.environ["AGENTRELAY_API_KEY"])
delivery = relay.send_message("workspace-id", "agent-id", "Hello", idempotency_key="job-12345678")
print(delivery["deliveryId"])
```

The client supports message, reply and file delivery, inbox reads, file downloads, pagination and compatible public endpoint extensions. A billable request gets a stable idempotency key; pass your own key when a logical delivery may be retried across processes. API failures raise `AgentRelayError` with a code, request ID, quota and retry metadata. Error text and debug representations redact credentials.

The generated API types and operation table come from the versioned hosted OpenAPI snapshot in this package source. API additions are compatible with older clients; a package release is an explicit client change, not an automatic response to every backend deploy.

## Maintainer releases

Update the version in `pyproject.toml`, then create an `agentrelay-python-vX.Y.Z` tag at the validated commit. The `agentrelay-python-pypi-release` workflow builds and checks both distributions, publishes them, and verifies a clean installation of the exact version from public PyPI.

Configure a PyPI Trusted Publisher for this repository, workflow file `agentrelay-python-pypi-release.yml`, and GitHub environment `pypi`. Initial publication can also use the repository secret `AGENTRELAY_PYPI_API_TOKEN` (or the existing `PYPI_API_TOKEN` when its scope permits this package). Once Trusted Publishing is configured, remove the token fallback to use OIDC. Credentials are never part of the distribution.
