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 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.

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:

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.