diff --git a/python/samples/02-agents/providers/telnyx/README.md b/python/samples/02-agents/providers/telnyx/README.md new file mode 100644 index 0000000000..b2bb54b623 --- /dev/null +++ b/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/) diff --git a/python/samples/02-agents/providers/telnyx/telnyx_chat_completion.py b/python/samples/02-agents/providers/telnyx/telnyx_chat_completion.py new file mode 100644 index 0000000000..2cda8d6dea --- /dev/null +++ b/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... +""" diff --git a/python/samples/02-agents/providers/telnyx/telnyx_embeddings.py b/python/samples/02-agents/providers/telnyx/telnyx_embeddings.py new file mode 100644 index 0000000000..8c448353d5 --- /dev/null +++ b/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! +"""