Metadata-Version: 2.4
Name: dial-autogen
Version: 0.10.0
Summary: Official Dial AutoGen tools — phone numbers, SMS, OTP, and voice calls for Microsoft AutoGen agents
Requires-Python: >=3.11
Requires-Dist: autogen-agentchat>=0.4
Requires-Dist: autogen-core>=0.4
Requires-Dist: dial-sdk
Description-Content-Type: text/markdown

# dial-autogen

Official Dial tools for [Microsoft AutoGen](https://microsoft.github.io/autogen/) — give an
AutoGen agent the ability to send SMS, receive OTP codes, and place AI voice calls through
[Dial](https://getdial.ai). Agents automating signups and web tasks get a real phone identity.

It's the AutoGen sibling of [`dial-langchain`](https://pypi.org/project/dial-langchain/) and
[`dial-crewai`](https://pypi.org/project/dial-crewai/): each tool is an
[`autogen_core.tools.FunctionTool`](https://microsoft.github.io/autogen/stable//user-guide/core-user-guide/components/tools.html)
wrapping the [`dial-sdk`](https://pypi.org/project/dial-sdk/) client. It adds nothing to the REST
contract — it just shapes Dial's operations into AutoGen tools.

> Targeting Microsoft's newer **Agent Framework** instead of AutoGen? Use
> [`dial-agentframework`](https://pypi.org/project/dial-agentframework/).

## Install

```bash
pip install dial-autogen
```

This pulls in `dial-sdk` and `autogen-agentchat`.

## Give the tools to an agent

Build one `DialClient`, pass it to `dial_tools`, and hand the result to an
`AssistantAgent`. Every tool shares that one client — a single connection pool for the
whole agent session — and you own its lifecycle (`await client.close()` when done):

```python
from autogen_agentchat.agents import AssistantAgent
from autogen_ext.models.openai import AzureOpenAIChatCompletionClient
from dial_sdk import DialClient, DialConfig
from dial_autogen import dial_tools

dial = DialClient(DialConfig(api_key="sk_live_..."))  # close with `await dial.close()`

model_client = AzureOpenAIChatCompletionClient(
    azure_deployment="gpt-4o",
    model="gpt-4o",
    api_version="2024-10-21",
    azure_endpoint="https://<your-resource>.openai.azure.com/",
)

agent = AssistantAgent(
    name="phone_agent",
    model_client=model_client,
    tools=dial_tools(dial),
    system_message="You operate the team's Dial phone number for SMS, OTP, and voice calls.",
)
```

`DialConfig` also takes an optional `base_url` to target a non-default deployment.

### Or pick individual tools

Each builder takes the shared `DialClient` and returns one `FunctionTool`:

```python
from dial_autogen import send_message_tool, wait_for_message_tool

tools = [
    send_message_tool(dial),
    wait_for_message_tool(dial),
]
```

## Available tools

Each builder takes your shared `DialClient`:

| Builder | Tool name | Action |
|---|---|---|
| `list_numbers_tool` | `list_numbers` | List your phone numbers |
| `purchase_number_tool` | `purchase_number` | Provision a new number (billable) |
| `set_number_properties_tool` | `set_number_properties` | Update a number's nickname / inbound instruction |
| `send_message_tool` | `send_message` | Send an SMS (optionally MMS) |
| `list_messages_tool` | `list_messages` | List recent messages |
| `make_call_tool` | `make_call` | Place an AI voice call |
| `list_calls_tool` | `list_calls` | List recent calls |
| `get_call_tool` | `get_call` | Fetch one call by id |
| `get_billing_tool` | `get_billing` | Credit balance, subscription, per-number mode |
| `wait_for_message_tool` | `wait_for_message` | Block until the next inbound SMS arrives, or time out |

## OTP flow

The point of phone identity for an agent: send a code and read the reply.
`wait_for_message` blocks until the next inbound SMS arrives, so an agent can:

1. trigger a signup that texts a code to your Dial number,
2. call `wait_for_message` to read the inbound code,
3. enter it back into the signup form.

See [`examples/signup_autogen.ipynb`](./examples/signup_autogen.ipynb) for a runnable agent.

## Notes

- AutoGen runs tools in an async loop, so these tools are **async-native** — no
  async→sync bridge (the one difference from the CrewAI sibling).
- `send_message` is a write action and **isn't idempotent** — a re-invoke after a
  failure can send a duplicate. `make_call` accepts an `idempotency_key`.
- `wait_for_message` is backed by Dial's **presence-based** event stream — for
  durable, at-least-once delivery, register a
  [webhook](https://docs.getdial.ai/documentation/platform/webhooks).

See the [AutoGen integration docs](https://docs.getdial.ai/documentation/sdks/autogen)
for the full guide.
