agent-framework-hosting-telegram 1.0.0a260721__tar.gz

agent_framework_hosting_telegram-1.0.0a260721/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

agent_framework_hosting_telegram-1.0.0a260721/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: agent-framework-hosting-telegram
+Version: 1.0.0a260721
+Summary: Telegram Bot API-shaped helpers for agent-framework-hosting.
+Author-email: Microsoft <af-support@microsoft.com>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+License-File: LICENSE
+Requires-Dist: agent-framework-core>=1.11.0,<2
+Requires-Dist: agent-framework-hosting==1.0.0a260721
+Project-URL: homepage, https://aka.ms/agent-framework
+Project-URL: issues, https://github.com/microsoft/agent-framework/issues
+Project-URL: release_notes, https://github.com/microsoft/agent-framework/releases?q=tag%3Apython-1&expanded=true
+Project-URL: source, https://github.com/microsoft/agent-framework/tree/main/python
+
+# agent-framework-hosting-telegram
+
+Telegram Bot API-shaped helpers for app-owned Agent Framework hosting.
+
+This is an alpha, helper-only package: it converts between Telegram's
+`Update` JSON shape and Agent Framework run values in both directions. It
+does **not** provide a bot client, a hosting/channel registry, or a
+long-running service. Your app remains fully responsible for:
+
+- **Fetching updates** -- long polling (`getUpdates`) or registering a
+  webhook -- and for verifying webhook authenticity (e.g. Telegram's secret
+  token header, or an IP allowlist).
+- **The Bot API client** -- issuing the actual HTTP calls (`sendMessage`,
+  `sendPhoto`, `editMessageText`, `answerCallbackQuery`, `getFile`, ...) with
+  whatever HTTP library you prefer.
+- **Rate limits and retries** -- Telegram enforces per-chat and global rate
+  limits; back off and retry on `429`/`5xx` yourself.
+- **Command dispatch** -- `telegram_command(...)` only parses and normalizes
+  a leading `/command`; your app decides what each command does.
+- **Sessions/storage** -- pair these helpers with
+  [`agent-framework-hosting`](https://pypi.org/project/agent-framework-hosting/)'s
+  `AgentState` / `SessionStore` (or your own) to persist `AgentSession`s across turns.
+
+## Helpers
+
+- `telegram_chat_id(update)` -- the chat id an update belongs to.
+- `telegram_session_id(update, bot_id=...)` -- a bot-scoped `AgentState`
+  session id. Private chats use `telegram:<bot_id>:<user_id>`; other chats use
+  `telegram:<bot_id>:<chat_id>`.
+- `telegram_command(update)` -- a leading slash command, with `/name@bot args`
+  normalized to `/name args`. Returns `None` if there is none.
+- `telegram_callback_query_id(update)` -- a callback query's id, so you can
+  call `answerCallbackQuery` yourself.
+- `telegram_media_file_id(update_or_message)` -- the `(file_id, mime_type)`
+  of inbound media (largest photo size, document, voice, audio, or video).
+- `telegram_to_run(update, *, resolve_file_url=None, stream=False)` -- convert
+  a `message`, `edited_message`, or `callback_query` update into
+  `Agent.run` arguments. Provide `resolve_file_url` (typically backed by
+  `getFile`) to turn inbound media into content; without it (or when it
+  returns `None`), text/caption is preserved and media is otherwise dropped.
+  Media-only input with no resolvable URL raises `ValueError`.
+- `telegram_from_run(result, *, chat_id, parse_mode=None)` -- render a
+  finished run as one `TelegramOperation` (`sendPhoto` when the response has
+  an image, otherwise `sendMessage`, falling back to `"(no response)"`).
+- `telegram_from_streaming_run(stream, *, chat_id, message_id,
+  initial_text=None, parse_mode=None)` -- render a streaming run as
+  `editMessageText` operations with the cumulative text so far, followed by any
+  images in the final response as `sendPhoto` operations. Pass the
+  app-created placeholder text as `initial_text` so an identical first edit is
+  omitted. Image-only responses first emit `deleteMessage` for the placeholder.
+
+`TelegramOperation` is a minimal `TypedDict` of `{"method": str, "payload": dict}`
+-- your app is responsible for actually calling the Bot API with it.
+
+```python
+from agent_framework_hosting import AgentState
+from agent_framework_hosting_telegram import (
+    telegram_chat_id,
+    telegram_from_run,
+    telegram_session_id,
+    telegram_to_run,
+)
+
+state = AgentState(agent)
+
+
+async def handle_update(update: dict) -> None:
+    chat_id = telegram_chat_id(update)
+    if chat_id is None:
+        return  # Not a chat update this bot handles.
+
+    session_id = telegram_session_id(update, bot_id=bot.id)
+    session = await state.get_or_create_session(session_id)
+    run = await telegram_to_run(update, resolve_file_url=resolve_telegram_file_url)
+    result = await (await state.get_target()).run(run["messages"], session=session, options=run["options"])
+    await state.set_session(session_id, session)  # type: ignore[arg-type]
+
+    operation = telegram_from_run(result, chat_id=chat_id)
+    await call_bot_api(operation["method"], operation["payload"])  # Your HTTP client.
+```
+
+The base execution-state helpers live in
+[`agent-framework-hosting`](https://pypi.org/project/agent-framework-hosting/).
+

agent_framework_hosting_telegram-1.0.0a260721/README.md

@@ -0,0 +1,83 @@
+# agent-framework-hosting-telegram
+
+Telegram Bot API-shaped helpers for app-owned Agent Framework hosting.
+
+This is an alpha, helper-only package: it converts between Telegram's
+`Update` JSON shape and Agent Framework run values in both directions. It
+does **not** provide a bot client, a hosting/channel registry, or a
+long-running service. Your app remains fully responsible for:
+
+- **Fetching updates** -- long polling (`getUpdates`) or registering a
+  webhook -- and for verifying webhook authenticity (e.g. Telegram's secret
+  token header, or an IP allowlist).
+- **The Bot API client** -- issuing the actual HTTP calls (`sendMessage`,
+  `sendPhoto`, `editMessageText`, `answerCallbackQuery`, `getFile`, ...) with
+  whatever HTTP library you prefer.
+- **Rate limits and retries** -- Telegram enforces per-chat and global rate
+  limits; back off and retry on `429`/`5xx` yourself.
+- **Command dispatch** -- `telegram_command(...)` only parses and normalizes
+  a leading `/command`; your app decides what each command does.
+- **Sessions/storage** -- pair these helpers with
+  [`agent-framework-hosting`](https://pypi.org/project/agent-framework-hosting/)'s
+  `AgentState` / `SessionStore` (or your own) to persist `AgentSession`s across turns.
+
+## Helpers
+
+- `telegram_chat_id(update)` -- the chat id an update belongs to.
+- `telegram_session_id(update, bot_id=...)` -- a bot-scoped `AgentState`
+  session id. Private chats use `telegram:<bot_id>:<user_id>`; other chats use
+  `telegram:<bot_id>:<chat_id>`.
+- `telegram_command(update)` -- a leading slash command, with `/name@bot args`
+  normalized to `/name args`. Returns `None` if there is none.
+- `telegram_callback_query_id(update)` -- a callback query's id, so you can
+  call `answerCallbackQuery` yourself.
+- `telegram_media_file_id(update_or_message)` -- the `(file_id, mime_type)`
+  of inbound media (largest photo size, document, voice, audio, or video).
+- `telegram_to_run(update, *, resolve_file_url=None, stream=False)` -- convert
+  a `message`, `edited_message`, or `callback_query` update into
+  `Agent.run` arguments. Provide `resolve_file_url` (typically backed by
+  `getFile`) to turn inbound media into content; without it (or when it
+  returns `None`), text/caption is preserved and media is otherwise dropped.
+  Media-only input with no resolvable URL raises `ValueError`.
+- `telegram_from_run(result, *, chat_id, parse_mode=None)` -- render a
+  finished run as one `TelegramOperation` (`sendPhoto` when the response has
+  an image, otherwise `sendMessage`, falling back to `"(no response)"`).
+- `telegram_from_streaming_run(stream, *, chat_id, message_id,
+  initial_text=None, parse_mode=None)` -- render a streaming run as
+  `editMessageText` operations with the cumulative text so far, followed by any
+  images in the final response as `sendPhoto` operations. Pass the
+  app-created placeholder text as `initial_text` so an identical first edit is
+  omitted. Image-only responses first emit `deleteMessage` for the placeholder.
+
+`TelegramOperation` is a minimal `TypedDict` of `{"method": str, "payload": dict}`
+-- your app is responsible for actually calling the Bot API with it.
+
+```python
+from agent_framework_hosting import AgentState
+from agent_framework_hosting_telegram import (
+    telegram_chat_id,
+    telegram_from_run,
+    telegram_session_id,
+    telegram_to_run,
+)
+
+state = AgentState(agent)
+
+
+async def handle_update(update: dict) -> None:
+    chat_id = telegram_chat_id(update)
+    if chat_id is None:
+        return  # Not a chat update this bot handles.
+
+    session_id = telegram_session_id(update, bot_id=bot.id)
+    session = await state.get_or_create_session(session_id)
+    run = await telegram_to_run(update, resolve_file_url=resolve_telegram_file_url)
+    result = await (await state.get_target()).run(run["messages"], session=session, options=run["options"])
+    await state.set_session(session_id, session)  # type: ignore[arg-type]
+
+    operation = telegram_from_run(result, chat_id=chat_id)
+    await call_bot_api(operation["method"], operation["payload"])  # Your HTTP client.
+```
+
+The base execution-state helpers live in
+[`agent-framework-hosting`](https://pypi.org/project/agent-framework-hosting/).

agent_framework_hosting_telegram-1.0.0a260721/agent_framework_hosting_telegram/__init__.py

@@ -0,0 +1,43 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Telegram Bot API-shaped helpers for app-owned Agent Framework hosting."""
+
+import importlib.metadata
+
+from ._parsing import (
+    ResolveFileUrl,
+    telegram_callback_query_id,
+    telegram_chat_id,
+    telegram_command,
+    telegram_media_file_id,
+    telegram_session_id,
+    telegram_to_run,
+)
+from ._rendering import (
+    TELEGRAM_MAX_CAPTION_LENGTH,
+    TELEGRAM_MAX_TEXT_LENGTH,
+    TelegramOperation,
+    telegram_from_run,
+    telegram_from_streaming_run,
+)
+
+try:
+    __version__ = importlib.metadata.version(__name__)
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "TELEGRAM_MAX_CAPTION_LENGTH",
+    "TELEGRAM_MAX_TEXT_LENGTH",
+    "ResolveFileUrl",
+    "TelegramOperation",
+    "__version__",
+    "telegram_callback_query_id",
+    "telegram_chat_id",
+    "telegram_command",
+    "telegram_from_run",
+    "telegram_from_streaming_run",
+    "telegram_media_file_id",
+    "telegram_session_id",
+    "telegram_to_run",
+]

agent_framework_hosting_telegram-1.0.0a260721/agent_framework_hosting_telegram/_parsing.py

@@ -0,0 +1,338 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Parsing helpers for the Telegram Bot API ``Update`` object.
+
+Telegram delivers updates as JSON objects shaped like ``{"update_id": ...,
+"message": {...}}`` (or ``edited_message`` / ``callback_query`` instead of
+``message``). These helpers pull out the handful of fields an app-owned route
+needs -- chat id, a namespaced session id, a leading slash command, a
+callback query id, and inbound media -- and translate an update into Agent
+Framework ``Agent.run`` arguments. They do not poll for updates, register
+webhooks, call the Telegram HTTP API, or dispatch commands; that is app-owned
+route/bot-client code.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Awaitable, Callable, Mapping, Sequence
+from typing import Any, cast
+
+from agent_framework import ChatOptions, Content, Message
+from agent_framework_hosting import AgentRunArgs
+
+# Telegram media fields whose objects carry a `file_id` (and, except photos,
+# a `mime_type`) directly, mapped to the MIME type Telegram uses when the
+# object omits `mime_type` (voice notes are always OGG/Opus, for example).
+_MEDIA_DEFAULT_MIME_TYPES: dict[str, str] = {
+    "document": "application/octet-stream",
+    "voice": "audio/ogg",
+    "audio": "audio/mpeg",
+    "video": "video/mp4",
+}
+
+# Matches a leading Telegram bot command: `/name`, optionally `@botname`,
+# optionally followed by arguments. Command names are `[A-Za-z0-9_]` per the
+# Bot API's `bot_command` entity rules.
+_COMMAND_PATTERN = re.compile(r"^/(?P<name>[A-Za-z0-9_]+)(?:@(?P<bot>[A-Za-z0-9_]+))?(?P<rest>.*)$", re.DOTALL)
+
+ResolveFileUrl = Callable[[str], Awaitable[str | None]]
+"""Async callable resolving a Telegram ``file_id`` to a fetchable URL, or ``None``."""
+
+
+def _inner_message(update: Mapping[str, Any]) -> Mapping[str, Any] | None:
+    """Return the ``message`` or ``edited_message`` object from ``update``, if present."""
+    for key in ("message", "edited_message"):
+        candidate = update.get(key)
+        if isinstance(candidate, Mapping):
+            return cast("Mapping[str, Any]", candidate)
+    return None
+
+
+def _callback_query(update: Mapping[str, Any]) -> Mapping[str, Any] | None:
+    """Return the ``callback_query`` object from ``update``, if present."""
+    candidate = update.get("callback_query")
+    return cast("Mapping[str, Any]", candidate) if isinstance(candidate, Mapping) else None
+
+
+def telegram_chat_id(update: Mapping[str, Any]) -> int | None:
+    """Return the chat id an update belongs to.
+
+    Reads ``message.chat.id`` / ``edited_message.chat.id``, falling back to
+    ``callback_query.message.chat.id`` for callback-only updates.
+
+    Args:
+        update: A Telegram Bot API ``Update`` object.
+
+    Returns:
+        The chat id, or ``None`` if the update carries none of the supported shapes.
+    """
+    message = _inner_message(update)
+    if message is None:
+        callback_query = _callback_query(update)
+        candidate = callback_query.get("message") if callback_query is not None else None
+        if not isinstance(candidate, Mapping):
+            return None
+        message = cast("Mapping[str, Any]", candidate)
+    chat_candidate = message.get("chat")
+    if not isinstance(chat_candidate, Mapping):
+        return None
+    chat = cast("Mapping[str, Any]", chat_candidate)
+    chat_id = chat.get("id")
+    return chat_id if isinstance(chat_id, int) else None
+
+
+def telegram_session_id(update: Mapping[str, Any], *, bot_id: int) -> str | None:
+    """Return a session id using Telegram's native bot, user, and chat boundaries.
+
+    Args:
+        update: A Telegram Bot API ``Update`` object.
+
+    Keyword Args:
+        bot_id: The Telegram bot's numeric user id.
+
+    Returns:
+        ``telegram:<bot_id>:<user_id>`` for a private chat,
+        ``telegram:<bot_id>:<chat_id>`` for other chats, or ``None`` when the
+        required Telegram identity is absent.
+    """
+    chat_id = telegram_chat_id(update)
+    if chat_id is None:
+        return None
+
+    message = _inner_message(update)
+    callback_query = _callback_query(update)
+    if message is None and callback_query is not None:
+        callback_message = callback_query.get("message")
+        if isinstance(callback_message, Mapping):
+            message = cast("Mapping[str, Any]", callback_message)
+
+    chat_candidate = message.get("chat") if message is not None else None
+    chat = cast("Mapping[str, Any]", chat_candidate) if isinstance(chat_candidate, Mapping) else None
+    chat_type = chat.get("type") if chat is not None else None
+    if chat_type != "private":
+        return f"telegram:{bot_id}:{chat_id}"
+
+    if callback_query is not None:
+        sender_candidate = callback_query.get("from")
+    elif message is not None:
+        sender_candidate = message.get("from")
+    else:
+        return None
+    if not isinstance(sender_candidate, Mapping):
+        return None
+    sender = cast("Mapping[str, Any]", sender_candidate)
+    sender_id = sender.get("id")
+    return f"telegram:{bot_id}:{sender_id}" if isinstance(sender_id, int) else None
+
+
+def telegram_callback_query_id(update: Mapping[str, Any]) -> str | None:
+    """Return the callback query id from an update, if present.
+
+    Apps need this to answer the callback query (``answerCallbackQuery``) so
+    Telegram stops showing the client-side loading spinner; this helper only
+    extracts the id, it does not call the Bot API.
+
+    Args:
+        update: A Telegram Bot API ``Update`` object.
+
+    Returns:
+        The callback query id, or ``None`` if the update has no ``callback_query``.
+    """
+    callback_query = _callback_query(update)
+    if callback_query is None:
+        return None
+    query_id = callback_query.get("id")
+    return query_id if isinstance(query_id, str) else None
+
+
+def _command_source_text(update: Mapping[str, Any]) -> str | None:
+    """Return the text a leading command should be parsed from."""
+    message = _inner_message(update)
+    if message is not None:
+        text = message.get("text")
+        if isinstance(text, str):
+            return text
+    callback_query = _callback_query(update)
+    if callback_query is not None:
+        data = callback_query.get("data")
+        if isinstance(data, str):
+            return data
+    return None
+
+
+def telegram_command(update: Mapping[str, Any]) -> str | None:
+    """Parse a leading slash command out of an update, without dispatching it.
+
+    Looks at ``message.text`` / ``edited_message.text`` first, then
+    ``callback_query.data``. A bot-suffixed command (``/name@bot args``) is
+    normalized to ``/name args`` since a single Bot API integration only ever
+    serves one bot username. Callers are responsible for matching the
+    returned command name and acting on it.
+
+    Args:
+        update: A Telegram Bot API ``Update`` object.
+
+    Returns:
+        The normalized command (e.g. ``"/start"`` or ``"/start hello"``), or
+        ``None`` if the source text does not start with a command.
+    """
+    text = _command_source_text(update)
+    if text is None:
+        return None
+    match = _COMMAND_PATTERN.match(text)
+    if not match:
+        return None
+    return f"/{match.group('name')}{match.group('rest')}".rstrip()
+
+
+def _resolve_media_message(update_or_message: Mapping[str, Any]) -> Mapping[str, Any] | None:
+    """Return the message object to inspect for media, from either an update or a bare message."""
+    if "message" in update_or_message or "edited_message" in update_or_message or "callback_query" in update_or_message:
+        message = _inner_message(update_or_message)
+        if message is not None:
+            return message
+        callback_query = _callback_query(update_or_message)
+        if callback_query is not None:
+            candidate = callback_query.get("message")
+            if isinstance(candidate, Mapping):
+                return cast("Mapping[str, Any]", candidate)
+        return None
+    return update_or_message
+
+
+def _largest_photo_file_id(photo_sizes: Sequence[Any]) -> str | None:
+    """Return the ``file_id`` of the highest-resolution entry in a Telegram ``photo`` array."""
+    candidates = [cast("Mapping[str, Any]", size) for size in photo_sizes if isinstance(size, Mapping)]
+    if not candidates:
+        return None
+
+    def _area(size: Mapping[str, Any]) -> int:
+        file_size = size.get("file_size")
+        if isinstance(file_size, int):
+            return file_size
+        width, height = size.get("width"), size.get("height")
+        return width * height if isinstance(width, int) and isinstance(height, int) else 0
+
+    largest = max(candidates, key=_area)
+    file_id = largest.get("file_id")
+    return file_id if isinstance(file_id, str) else None
+
+
+def telegram_media_file_id(update_or_message: Mapping[str, Any]) -> tuple[str, str] | None:
+    """Return the ``(file_id, mime_type)`` of the inbound media attached to an update or message.
+
+    Accepts either a full ``Update`` object (media is read from ``message`` /
+    ``edited_message`` / ``callback_query.message``) or a bare Telegram
+    message object. Photos pick the largest size Telegram sent (by
+    ``file_size``, falling back to pixel area); documents, voice notes,
+    audio, and video use their own ``file_id`` and ``mime_type`` (falling
+    back to Telegram's known default MIME type when the field is absent).
+
+    Args:
+        update_or_message: A Telegram ``Update`` or message object.
+
+    Returns:
+        A ``(file_id, mime_type)`` tuple, or ``None`` if there is no supported media.
+    """
+    message = _resolve_media_message(update_or_message)
+    if message is None:
+        return None
+
+    photo = message.get("photo")
+    if isinstance(photo, Sequence) and not isinstance(photo, (str, bytes, bytearray)) and photo:
+        file_id = _largest_photo_file_id(cast("Sequence[Any]", photo))
+        if file_id is not None:
+            return file_id, "image/jpeg"
+
+    for key, default_mime_type in _MEDIA_DEFAULT_MIME_TYPES.items():
+        item_candidate = message.get(key)
+        if isinstance(item_candidate, Mapping):
+            item = cast("Mapping[str, Any]", item_candidate)
+            file_id = item.get("file_id")
+            if isinstance(file_id, str):
+                mime_type = item.get("mime_type")
+                return file_id, mime_type if isinstance(mime_type, str) and mime_type else default_mime_type
+    return None
+
+
+async def _contents_from_message(
+    message: Mapping[str, Any],
+    resolve_file_url: ResolveFileUrl | None,
+) -> list[Content]:
+    """Translate one Telegram message object into Agent Framework content parts.
+
+    Raises:
+        ValueError: If the message has no text, caption, or resolvable media.
+    """
+    text = message.get("text")
+    caption = message.get("caption")
+    text_value = text if isinstance(text, str) and text else (caption if isinstance(caption, str) and caption else None)
+
+    contents: list[Content] = []
+    media = telegram_media_file_id(message)
+    if media is not None:
+        file_id, mime_type = media
+        resolved_url = await resolve_file_url(file_id) if resolve_file_url is not None else None
+        if resolved_url:
+            contents.append(Content.from_uri(uri=resolved_url, media_type=mime_type))
+        elif text_value is None:
+            raise ValueError(
+                f"Cannot resolve Telegram media file_id={file_id!r}: no `resolve_file_url` was given (or it "
+                "returned None), and the message has no text/caption to fall back to."
+            )
+    if text_value is not None:
+        contents.append(Content.from_text(text=text_value))
+
+    if not contents:
+        raise ValueError("Telegram message has no text, caption, or resolvable media to convert to a run.")
+    return contents
+
+
+async def telegram_to_run(
+    update: Mapping[str, Any],
+    *,
+    resolve_file_url: ResolveFileUrl | None = None,
+    stream: bool = False,
+) -> AgentRunArgs:
+    """Convert a Telegram update into Agent Framework run values.
+
+    Supports ``message``, ``edited_message``, and ``callback_query`` updates.
+    Message/edited-message text or caption becomes text content; inbound
+    media becomes uri content when ``resolve_file_url`` resolves it (media
+    alone with no resolvable URL and no text/caption raises rather than
+    producing an empty run). A callback query's ``data`` becomes the user's
+    text.
+
+    Args:
+        update: A Telegram Bot API ``Update`` object.
+
+    Keyword Args:
+        resolve_file_url: Optional async callable that resolves a Telegram
+            ``file_id`` (typically via the Bot API's ``getFile``) to a
+            fetchable URL, or ``None`` if it cannot. When omitted, media is
+            ignored and only text/caption is used.
+        stream: Whether the caller intends to run the agent in streaming mode.
+
+    Returns:
+        Arguments corresponding to ``Agent.run``.
+
+    Raises:
+        ValueError: If the update has no actionable message/callback data, or
+            a message has no text, caption, or resolvable media.
+    """
+    message = _inner_message(update)
+    if message is not None:
+        contents = await _contents_from_message(message, resolve_file_url)
+    else:
+        callback_query = _callback_query(update)
+        data = callback_query.get("data") if callback_query is not None else None
+        if not isinstance(data, str) or not data:
+            raise ValueError("Telegram update has no actionable `message`, `edited_message`, or `callback_query.data`.")
+        contents = [Content.from_text(text=data)]
+
+    return AgentRunArgs(
+        messages=[Message("user", contents)],
+        options=cast("ChatOptions[Any]", {}),
+        stream=stream,
+    )

agent_framework_hosting_telegram-1.0.0a260721/agent_framework_hosting_telegram/_rendering.py

@@ -0,0 +1,171 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Rendering helpers that translate Agent Framework results into native Telegram Bot API calls.
+
+Each helper returns (or yields) a small ``TelegramOperation`` -- a Telegram
+Bot API method name plus its JSON payload. App-owned code decides how to
+actually invoke the Bot API (``sendMessage``, ``sendPhoto``,
+``editMessageText``, ...), including authentication, retries, and rate
+limiting; these helpers make no network calls.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import Any, TypedDict
+
+from agent_framework import AgentResponse, AgentResponseUpdate, ResponseStream
+
+# Telegram's documented maximum length, in UTF-16 code units, for message
+# text (`sendMessage` / `editMessageText`) and photo captions (`sendPhoto`).
+TELEGRAM_MAX_TEXT_LENGTH = 4096
+TELEGRAM_MAX_CAPTION_LENGTH = 1024
+
+_NO_RESPONSE_TEXT = "(no response)"
+
+
+class TelegramOperation(TypedDict):
+    """A single native Telegram Bot API call produced by a rendering helper.
+
+    Attributes:
+        method: The Telegram Bot API method name (e.g. ``"sendMessage"``).
+        payload: The JSON-serializable request body for that method.
+    """
+
+    method: str
+    payload: dict[str, Any]
+
+
+def _truncate(text: str, max_length: int) -> str:
+    """Deterministically cap ``text`` at ``max_length`` UTF-16 code units."""
+    units = 0
+    for index, char in enumerate(text):
+        units += 2 if ord(char) > 0xFFFF else 1
+        if units > max_length:
+            return text[:index]
+    return text
+
+
+def _text_and_image_uris(result: AgentResponse[Any]) -> tuple[str, list[str]]:
+    """Return the response's concatenated text and any image uris it carries."""
+    image_uris = [
+        content.uri
+        for message in result.messages
+        for content in message.contents
+        if content.type == "uri" and content.uri and (content.media_type or "").startswith("image/")
+    ]
+    return result.text, image_uris
+
+
+def telegram_from_run(
+    result: AgentResponse[Any],
+    *,
+    chat_id: int,
+    parse_mode: str | None = None,
+) -> TelegramOperation:
+    """Render a finished agent run as one native Telegram Bot API call.
+
+    An image in the response renders as ``sendPhoto`` (using the first image
+    found; any accompanying text becomes its caption). Otherwise, response
+    text renders as ``sendMessage``, falling back to ``"(no response)"`` when
+    the response has neither text nor an image.
+
+    Args:
+        result: The finished agent response to render.
+
+    Keyword Args:
+        chat_id: The Telegram chat id to address the message to.
+        parse_mode: Optional Telegram ``parse_mode`` (e.g. ``"MarkdownV2"``,
+            ``"HTML"``) to attach to the rendered payload.
+
+    Returns:
+        A ``TelegramOperation`` describing the Bot API call to make.
+    """
+    text, image_uris = _text_and_image_uris(result)
+    if image_uris:
+        payload: dict[str, Any] = {"chat_id": chat_id, "photo": image_uris[0]}
+        if text:
+            payload["caption"] = _truncate(text, TELEGRAM_MAX_CAPTION_LENGTH)
+            if parse_mode:
+                payload["parse_mode"] = parse_mode
+        return TelegramOperation(method="sendPhoto", payload=payload)
+
+    payload = {"chat_id": chat_id, "text": _truncate(text or _NO_RESPONSE_TEXT, TELEGRAM_MAX_TEXT_LENGTH)}
+    if parse_mode:
+        payload["parse_mode"] = parse_mode
+    return TelegramOperation(method="sendMessage", payload=payload)
+
+
+async def telegram_from_streaming_run(
+    stream: ResponseStream[AgentResponseUpdate, AgentResponse[Any]],
+    *,
+    chat_id: int,
+    message_id: int,
+    initial_text: str | None = None,
+    parse_mode: str | None = None,
+) -> AsyncIterator[TelegramOperation]:
+    """Render a streaming agent run as a sequence of native Telegram Bot API calls.
+
+    Yields one ``editMessageText`` operation per update carrying new text, each
+    with the cumulative text so far (Telegram has no incremental-append edit
+    call). Interim edits omit ``parse_mode`` since intermediate text is not
+    guaranteed to be valid in the target markup. After the stream ends, yields
+    a final ``editMessageText`` reflecting the finalized response text (this
+    one includes ``parse_mode`` when given) and then one ``sendPhoto``
+    operation per image the finalized response carries. Errors raised while
+    iterating the stream or while finalizing it (``stream.get_final_response()``)
+    propagate to the caller rather than being swallowed.
+
+    Args:
+        stream: The agent response stream returned by ``agent.run(..., stream=True)``.
+
+    Keyword Args:
+        chat_id: The Telegram chat id the streamed message lives in.
+        message_id: The id of the Telegram message to edit as new content arrives.
+        initial_text: The current text of the app-created placeholder message.
+            Matching edits are omitted because Telegram rejects no-op edits.
+        parse_mode: Optional Telegram ``parse_mode`` to attach to the final text edit.
+
+    Yields:
+        ``TelegramOperation`` values describing the Bot API calls to make, in order.
+    """
+    text = ""
+    last_rendered_text = _truncate(initial_text, TELEGRAM_MAX_TEXT_LENGTH) if initial_text is not None else ""
+    async for update in stream:
+        if update.text:
+            text += update.text
+            rendered_text = _truncate(text, TELEGRAM_MAX_TEXT_LENGTH)
+            if rendered_text == last_rendered_text:
+                continue
+            last_rendered_text = rendered_text
+            yield TelegramOperation(
+                method="editMessageText",
+                payload={
+                    "chat_id": chat_id,
+                    "message_id": message_id,
+                    "text": rendered_text,
+                },
+            )
+
+    final = await stream.get_final_response()
+    final_text, image_uris = _text_and_image_uris(final)
+
+    if final_text or not image_uris:
+        rendered_text = _truncate(final_text or _NO_RESPONSE_TEXT, TELEGRAM_MAX_TEXT_LENGTH)
+        payload: dict[str, Any] = {
+            "chat_id": chat_id,
+            "message_id": message_id,
+            "text": rendered_text,
+        }
+        if parse_mode:
+            payload["parse_mode"] = parse_mode
+        if rendered_text != last_rendered_text or parse_mode:
+            yield TelegramOperation(method="editMessageText", payload=payload)
+    else:
+        yield TelegramOperation(
+            method="deleteMessage",
+            payload={"chat_id": chat_id, "message_id": message_id},
+        )
+
+    for uri in image_uris:
+        yield TelegramOperation(method="sendPhoto", payload={"chat_id": chat_id, "photo": uri})

agent_framework_hosting_telegram-1.0.0a260721/pyproject.toml

@@ -0,0 +1,79 @@
+[project]
+name = "agent-framework-hosting-telegram"
+description = "Telegram Bot API-shaped helpers for agent-framework-hosting."
+authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
+readme = "README.md"
+requires-python = ">=3.10"
+version = "1.0.0a260721"
+license-files = ["LICENSE"]
+urls.homepage = "https://aka.ms/agent-framework"
+urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
+urls.release_notes = "https://github.com/microsoft/agent-framework/releases?q=tag%3Apython-1&expanded=true"
+urls.issues = "https://github.com/microsoft/agent-framework/issues"
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+dependencies = [
+    "agent-framework-core>=1.11.0,<2",
+    "agent-framework-hosting==1.0.0a260721",
+]
+
+[tool.uv]
+prerelease = "if-necessary-or-explicit"
+environments = [
+    "sys_platform == 'darwin'",
+    "sys_platform == 'linux'",
+    "sys_platform == 'win32'"
+]
+
+[tool.uv-dynamic-versioning]
+fallback-version = "0.0.0"
+
+[tool.pytest.ini_options]
+testpaths = 'tests'
+addopts = "-ra -q -r fEX"
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+filterwarnings = []
+timeout = 120
+markers = [
+    "integration: marks tests as integration tests that require external services",
+]
+
+[tool.ruff]
+extend = "../../pyproject.toml"
+
+[tool.coverage.run]
+omit = [
+    "**/__init__.py"
+]
+
+[tool.pyright]
+extends = "../../pyproject.toml"
+include = ["agent_framework_hosting_telegram"]
+exclude = ['tests']
+
+[tool.bandit]
+targets = ["agent_framework_hosting_telegram"]
+exclude_dirs = ["tests"]
+
+[tool.poe]
+executor.type = "uv"
+include = "../../shared_tasks.toml"
+
+[tool.poe.tasks.test]
+help = "Run the default unit test suite for this package."
+cmd = 'pytest -m "not integration" --cov=agent_framework_hosting_telegram --cov-report=term-missing:skip-covered tests'
+
+[build-system]
+requires = ["flit-core >= 3.11,<4.0"]
+build-backend = "flit_core.buildapi"