Python: Add Telnyx provider samples (OpenAI-compatible endpoint)

python/samples/02-agents/providers/telnyx/README.md

@@ -0,0 +1,55 @@
+# Telnyx Examples
+
+This folder contains examples demonstrating how to use Telnyx as an OpenAI-compatible inference provider with the Agent Framework.
+
+## Prerequisites
+
+1. **Telnyx Account**: Sign up at [portal.telnyx.com](https://portal.telnyx.com/) and obtain an API key
+2. **API Key**: Generate an API key from the Telnyx portal under "Auth Keys"
+
+## Overview
+
+Telnyx provides an OpenAI-compatible API at `https://api.telnyx.com/v2/ai/openai` that supports chat completions and embeddings. Since it's OpenAI-compatible, you can use the existing `OpenAIChatClient` and `OpenAIEmbeddingClient` from the `agent-framework-openai` package — no new provider package is needed.
+
+This follows the same pattern as the [Ollama with OpenAI Chat Client](../ollama/ollama_with_openai_chat_client.py) example, where an existing provider client is configured with a custom `base_url`.
+
+> **Note**: Available models depend on your Telnyx account configuration. Common models include Kimi-K2.5, GLM-5.1-FP8, MiniMax-M2.7, and Qwen3-235B-A22B. See the [Telnyx AI documentation](https://developers.telnyx.com/docs/api/ai) for the latest model list.
+
+## Examples
+
+| File | Description |
+|------|-------------|
+| `telnyx_chat_completion.py` | Basic chat completion using `OpenAIChatClient` with Telnyx endpoint. Shows both streaming and non-streaming responses. |
+| `telnyx_embeddings.py` | Text embeddings using `OpenAIEmbeddingClient` with Telnyx endpoint. |
+
+## Configuration
+
+Set the following environment variables:
+
+- `TELNYX_API_KEY` — Your Telnyx API key (required for all examples)
+  - Get one from [portal.telnyx.com](https://portal.telnyx.com/) → Auth Keys
+  - Example: `export TELNYX_API_KEY="KEY0192..."`
+
+- `TELNYX_MODEL` — Model name to use (optional, defaults to `"Kimi-K2.5"`)
+  - Example: `export TELNYX_MODEL="GLM-5.1-FP8"`
+
+- `TELNYX_EMBEDDING_MODEL` — Embedding model name (optional, defaults to `"thenlper/gte-large"`)
+  - Example: `export TELNYX_EMBEDDING_MODEL="thenlper/gte-large"`
+
+## Quick Start
+
+```bash
+# Install the Agent Framework OpenAI package and python-dotenv
+pip install agent-framework-openai python-dotenv
+
+# Set your Telnyx API key
+export TELNYX_API_KEY="your-api-key-here"
+
+# Run the basic chat completion example
+python telnyx_chat_completion.py
+```
+
+## Resources
+
+- [Telnyx AI API Documentation](https://developers.telnyx.com/docs/api/ai)
+- [Telnyx Portal](https://portal.telnyx.com/)

python/samples/02-agents/providers/telnyx/telnyx_chat_completion.py

@@ -0,0 +1,107 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+
+from agent_framework import Agent
+from agent_framework.openai import OpenAIChatClient
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+"""
+Telnyx Chat Completion Example
+
+This sample demonstrates using Telnyx as an OpenAI-compatible inference
+provider through the OpenAIChatClient by configuring the base_url to
+point to the Telnyx AI API endpoint.
+
+Telnyx provides an OpenAI-compatible API at https://api.telnyx.com/v2/ai/openai
+that supports chat completions, embeddings, and function/tool calling.
+
+Environment Variables:
+    TELNYX_API_KEY   — Your Telnyx API key (from https://portal.telnyx.com/)
+    TELNYX_MODEL     — Model name to use (default: "Kimi-K2.5")
+                       Available models include: Kimi-K2.5, GLM-5.1-FP8,
+                       MiniMax-M2.7, Qwen3-235B-A22B
+"""
+
+
+async def non_streaming_example() -> None:
+    """Example of non-streaming response (get the complete result at once)."""
+    print("=== Non-streaming Response Example ===")
+
+    # 1. Configure the OpenAI client to use Telnyx as the backend.
+    client = OpenAIChatClient(
+        api_key=os.getenv("TELNYX_API_KEY"),
+        base_url="https://api.telnyx.com/v2/ai/openai",
+        model=os.getenv("TELNYX_MODEL", "Kimi-K2.5"),
+    )
+
+    # 2. Create an agent that uses the Telnyx-backed client.
+    agent = Agent(
+        client=client,
+        name="TelnyxAgent",
+        instructions="You are a helpful assistant.",
+    )
+
+    # 3. Send a message and wait for the full response.
+    query = "What is the capital of France?"
+    print(f"User: {query}")
+    result = await agent.run(query)
+    print(f"Agent: {result}\n")
+
+
+async def streaming_example() -> None:
+    """Example of streaming response (get results as they are generated)."""
+    print("=== Streaming Response Example ===")
+
+    # 1. Configure the OpenAI client to use Telnyx as the backend.
+    client = OpenAIChatClient(
+        api_key=os.getenv("TELNYX_API_KEY"),
+        base_url="https://api.telnyx.com/v2/ai/openai",
+        model=os.getenv("TELNYX_MODEL", "Kimi-K2.5"),
+    )
+
+    # 2. Create an agent that uses the Telnyx-backed client.
+    agent = Agent(
+        client=client,
+        name="TelnyxAgent",
+        instructions="You are a helpful assistant.",
+    )
+
+    # 3. Send a message and stream the response token by token.
+    query = "Explain quantum computing in one paragraph."
+    print(f"User: {query}")
+    print("Agent: ", end="", flush=True)
+    async for chunk in agent.run(query, stream=True):
+        if chunk.text:
+            print(chunk.text, end="", flush=True)
+    print("\n")
+
+
+async def main() -> None:
+    print("=== Telnyx Chat Completion Agent Example ===")
+
+    await non_streaming_example()
+    await streaming_example()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+"""
+Sample output:
+
+=== Telnyx Chat Completion Agent Example ===
+=== Non-streaming Response Example ===
+User: What is the capital of France?
+Agent: The capital of France is Paris.
+
+=== Streaming Response Example ===
+User: Explain quantum computing in one paragraph.
+Agent: Quantum computing is a type of computation that harnesses quantum-mechanical
+phenomena, such as superposition and entanglement, to process information in ways that
+classical computers cannot...
+"""

python/samples/02-agents/providers/telnyx/telnyx_embeddings.py

@@ -0,0 +1,74 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+
+from agent_framework.openai import OpenAIEmbeddingClient
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+"""
+Telnyx Embeddings Example
+
+This sample demonstrates using Telnyx for text embeddings through the
+OpenAIEmbeddingClient by configuring the base_url to point to the
+Telnyx AI API endpoint.
+
+Telnyx provides an OpenAI-compatible API that supports embeddings
+generation using models like `thenlper/gte-large`.
+
+Environment Variables:
+    TELNYX_API_KEY   — Your Telnyx API key (from https://portal.telnyx.com/)
+    TELNYX_EMBEDDING_MODEL — Embedding model name (default: "thenlper/gte-large")
+"""
+
+
+async def main() -> None:
+    print("=== Telnyx Embeddings Example ===")
+
+    # 1. Configure the OpenAI embedding client to use Telnyx as the backend.
+    client = OpenAIEmbeddingClient(
+        api_key=os.getenv("TELNYX_API_KEY"),
+        base_url="https://api.telnyx.com/v2/ai/openai",
+        model=os.getenv("TELNYX_EMBEDDING_MODEL", "thenlper/gte-large"),
+    )
+
+    # 2. Generate embeddings for a list of texts.
+    texts = [
+        "Telnyx provides telecom infrastructure for AI agents.",
+        "Agent Framework makes it easy to build AI agents.",
+    ]
+
+    print(f"Generating embeddings for {len(texts)} texts...")
+    response = await client.get_embeddings(texts)
+
+    # 3. Print the embedding dimensions and a preview of each vector.
+    for i, embedding in enumerate(response):
+        print(f"Text {i + 1}: \"{texts[i]}\"")
+        print(f"  Dimensions: {embedding.dimensions}")
+        print(f"  Preview: [{', '.join(str(v) for v in embedding.vector[:5])}, ...]")
+        print()
+
+    print("Done!")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+"""
+Sample output:
+
+=== Telnyx Embeddings Example ===
+Generating embeddings for 2 texts...
+Text 1: "Telnyx provides telecom infrastructure for AI agents."
+  Dimensions: 1024
+  Preview: [0.0123, -0.0456, 0.0789, ...], ...
+
+Text 2: "Agent Framework makes it easy to build AI agents."
+  Dimensions: 1024
+  Preview: [0.0234, -0.0567, 0.0890, ...], ...
+
+Done!
+"""