Metadata-Version: 2.4
Name: telnyx-agent-toolkit
Version: 0.2.0
Summary: Telnyx Agent Toolkit — tools for building AI agents with Telnyx APIs
Project-URL: Homepage, https://github.com/team-telnyx/ai
Project-URL: Documentation, https://developers.telnyx.com
Project-URL: Repository, https://github.com/team-telnyx/ai
Project-URL: Issues, https://github.com/team-telnyx/ai/issues
Author-email: Telnyx <support@telnyx.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,sms,telecom,telnyx,toolkit,voice
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Telephony
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: all
Requires-Dist: crewai>=0.80.0; extra == 'all'
Requires-Dist: langchain-core>=0.3.0; extra == 'all'
Requires-Dist: openai>=1.0.0; extra == 'all'
Provides-Extra: crewai
Requires-Dist: crewai>=0.80.0; extra == 'crewai'
Provides-Extra: dev
Requires-Dist: pyright>=1.1.390; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-rerunfailures>=14.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: respx>=0.22.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3.0; extra == 'langchain'
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == 'openai'
Description-Content-Type: text/markdown

# Telnyx Agent Toolkit

Python SDK for building AI agents with [Telnyx](https://telnyx.com) APIs. Works with **OpenAI**, **LangChain**, and **CrewAI**.

## Installation

```bash
# Core (no framework dependency)
pip install telnyx-agent-toolkit

# With OpenAI support
pip install telnyx-agent-toolkit[openai]

# With LangChain support
pip install telnyx-agent-toolkit[langchain]

# With CrewAI support
pip install telnyx-agent-toolkit[crewai]

# Everything
pip install telnyx-agent-toolkit[all]
```

## Quick Start

### OpenAI

```python
import os
from openai import OpenAI
from telnyx_agent_toolkit import TelnyxAgentToolkit

toolkit = TelnyxAgentToolkit(
    api_key=os.environ["TELNYX_API_KEY"],
    configuration={
        "actions": {
            "messaging": {"send_sms": True},
            "numbers": {"list": True, "search": True},
            "account": {"get_balance": True},
        }
    },
)

client = OpenAI()
tools = toolkit.get_openai_tools()
executor = toolkit.get_openai_tool_executor()

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "What's my Telnyx balance?"}],
    tools=tools,
)

# Execute tool calls
for tool_call in response.choices[0].message.tool_calls:
    result = executor.execute(tool_call)
    print(result)
```

### LangChain

```python
from telnyx_agent_toolkit import TelnyxAgentToolkit

toolkit = TelnyxAgentToolkit(api_key="KEY...")
tools = toolkit.get_langchain_tools()

# Use with any LangChain agent
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="gpt-4o")
llm_with_tools = llm.bind_tools(tools)
```

### CrewAI

```python
from crewai import Agent
from telnyx_agent_toolkit import TelnyxAgentToolkit

toolkit = TelnyxAgentToolkit(api_key="KEY...")
tools = toolkit.get_crewai_tools()

agent = Agent(
    role="Telecom Specialist",
    goal="Help manage phone numbers and messaging",
    tools=tools,
)
```

## Configuration

Control which tools are available to the agent:

```python
toolkit = TelnyxAgentToolkit(
    api_key="KEY...",
    configuration={
        "actions": {
            # Messaging
            "messaging": {
                "send_sms": True,            # Send SMS/MMS
                "list_messaging_profiles": True,
                "create_messaging_profile": True,
            },
            # Phone Numbers
            "numbers": {
                "list": True,    # List account numbers
                "search": True,  # Search available numbers
                "buy": True,     # Purchase numbers (charges account)
            },
            # Account
            "account": {
                "get_balance": True,
            },
            # Voice
            "voice": {
                "make_call": True,
                "list_connections": True,
            },
            # AI
            "ai": {
                "chat": True,              # Chat completions
                "embed": True,             # Embeddings
                "list_ai_assistants": True,
                "create_ai_assistant": True,
            },
            # Fax
            "fax": {
                "send_fax": True,
            },
            # Lookup
            "lookup": {
                "lookup_number": True,     # Carrier/CNAM lookup
            },
            # IoT
            "iot": {
                "list_sim_cards": True,
            },
            # Verification
            "verify": {
                "verify_phone": True,      # Send verification code
                "verify_code": True,       # Check verification code
            },
        }
    },
)
```

> **No configuration = all tools enabled.** Use configuration to restrict which tools the agent can access.

## Available Tools

| Tool | Category | Description |
|------|----------|-------------|
| `send_sms` | Messaging | Send an SMS or MMS message |
| `list_messaging_profiles` | Messaging | List messaging profiles |
| `create_messaging_profile` | Messaging | Create a messaging profile |
| `list_phone_numbers` | Numbers | List phone numbers on the account |
| `search_phone_numbers` | Numbers | Search available numbers to buy |
| `buy_phone_number` | Numbers | Purchase a phone number |
| `get_balance` | Account | Check account balance |
| `make_call` | Voice | Initiate an outbound call |
| `list_connections` | Voice | List voice connections |
| `ai_chat` | AI | Chat completion via Telnyx inference |
| `ai_embed` | AI | Generate embeddings |
| `list_ai_assistants` | AI | List AI assistants |
| `create_ai_assistant` | AI | Create an AI assistant |
| `send_fax` | Fax | Send a fax |
| `lookup_number` | Lookup | Phone number lookup |
| `list_sim_cards` | IoT | List IoT SIM cards |
| `verify_phone` | Verify | Start phone verification |
| `verify_code` | Verify | Check verification code |

## Async Support

All tools support async execution natively:

```python
# Async execution
result = await executor.execute_async(tool_call)

# Direct tool execution
result = await toolkit.core.run_tool_async("get_balance", {})
```

## API Client

Access the underlying HTTP client directly:

```python
# Async
data = await toolkit.api_client.get_async("/phone_numbers")

# Sync
data = toolkit.api_client.get("/phone_numbers")
```

## Requirements

- Python 3.11+
- [Telnyx API key](https://portal.telnyx.com/#/app/api-keys)

## Development

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check .

# Type check
pyright
```

## License

MIT
