> ## Documentation Index
> Fetch the complete documentation index at: https://plivo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agno

> Give an Agno AI agent the ability to send SMS, place voice calls, and look up numbers using Plivo tools.

[Agno](https://github.com/agno-agi/agno) is an open-source framework for building AI agents. Plivo ships as a built-in toolkit in Agno, so an agent can send SMS, place voice calls, and look up phone numbers by calling Plivo APIs as tools. The agent's model decides when to use each tool, so you add the capability once and let the agent choose when to reach a person.

This is a tool-use integration over Plivo REST APIs.

## Prerequisites

| Requirement    | Description                                                                |
| -------------- | -------------------------------------------------------------------------- |
| Plivo account  | Your Auth ID and Auth Token from the [Plivo console](https://cx.plivo.com) |
| Plivo number   | An SMS-enabled number on your account to send from and call from           |
| Python         | 3.11 or newer                                                              |
| Model provider | An OpenAI API key                                                          |
| Answer URL     | A hosted answer URL that returns Plivo XML for outbound calls              |

## Quick start

Start with the runnable examples repository, then adapt the pattern to your own agent.

```bash theme={null}
git clone https://github.com/plivo-dev/agno-plivo-examples.git
cd agno-plivo-examples
uv sync
cp .env.example .env
```

Set your credentials in `.env`:

```bash theme={null}
OPENAI_API_KEY=your-openai-key
PLIVO_AUTH_ID=your-auth-id
PLIVO_AUTH_TOKEN=your-auth-token
PLIVO_FROM_NUMBER=your-plivo-number
PLIVO_TO_NUMBER=destination-number
PLIVO_ANSWER_URL=https://your-app.example.com/answer.xml
```

Run the featured example:

```bash theme={null}
uv run python examples/on_call_alerting.py
```

For call-capable examples, `PLIVO_ANSWER_URL` should point to an endpoint that returns valid Plivo XML.

If you want the smallest possible inline example, create an agent and give it the Plivo tools:

```python theme={null}
import os

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.tools.plivo import PlivoTools

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    tools=[PlivoTools()],
    instructions=[
        "Use Plivo to send SMS, place calls, and look up phone numbers.",
        f"When placing a call, use caller ID {os.environ['PLIVO_FROM_NUMBER']} ",
        f"and answer URL {os.environ['PLIVO_ANSWER_URL']} served over GET.",
    ],
    markdown=True,
)

agent.print_response(
    "Send an SMS from +14150000001 to +14150000002 saying the deploy is done."
)
```

The agent calls `send_sms` and returns the Plivo message ID.

For outbound calls, keep the caller ID and answer URL in config and let the per-call prompt express only intent:

```python theme={null}
agent.print_response("Call +14150000002 and remind them about the 3pm meeting.")
```

This works with the toolkit as it exists today. The model fills `make_call` from the configured instructions, while `PLIVO_ANSWER_URL` stays in env instead of being pasted into every call prompt.

<Note>
  The sender must be an SMS-enabled Plivo number on your account. For calls, the caller ID must be a voice-enabled Plivo number in E.164.
</Note>

## Available tools

`PlivoTools` registers these tools. The agent picks the right one from your instruction.

| Tool               | What it does                                                       |
| ------------------ | ------------------------------------------------------------------ |
| `send_sms`         | Send an SMS from a Plivo number to a recipient                     |
| `make_call`        | Place an outbound call that runs answer XML from a URL you provide |
| `lookup_number`    | Look up the country, carrier, and line type of a number            |
| `list_messages`    | List recent messages on the account                                |
| `list_calls`       | List recent calls on the account                                   |
| `get_call_details` | Fetch the details of a single call                                 |

For `make_call`, pass an `answer_url` that returns Plivo XML, and set `answer_method` to match how that URL is served.

## Register a subset of tools

Turn individual tools on or off with the `enable_*` flags.

```python theme={null}
PlivoTools(enable_send_sms=True, enable_make_call=True, enable_lookup_number=False)
```

## Troubleshooting

| Issue                                  | Solution                                                                                                             |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `authentication failed`                | Confirm `PLIVO_AUTH_ID` and `PLIVO_AUTH_TOKEN` are set to the values from the [Plivo console](https://cx.plivo.com). |
| SMS not delivered                      | Confirm the sender is an SMS-enabled Plivo number and that the destination country is supported for that number.     |
| Agent does not call a tool             | Make the instruction explicit and confirm the tool is enabled.                                                       |
| `make_call` connects but plays nothing | The `answer_url` must return valid Plivo XML, and `answer_method` must match how the URL is served.                  |

## Related

<CardGroup cols={2}>
  <Card title="Runnable examples" icon="code" href="https://github.com/plivo-dev/agno-plivo-examples">
    Clone-and-run Agno agents built on the Plivo tools.
  </Card>

  <Card title="Agno cookbook example" icon="book" href="https://github.com/agno-agi/agno/blob/main/cookbook/91_tools/plivo_tools.py">
    The Plivo tools example in the Agno cookbook.
  </Card>

  <Card title="Agno PlivoTools reference" icon="book-open" href="https://docs.agno.com/tools/toolkits/social/plivo">
    Agno's reference for the Plivo toolkit.
  </Card>

  <Card title="Plivo Messages API" icon="message-square" href="/docs/messaging/api/message/send-a-message">
    Send an SMS with the Plivo API.
  </Card>

  <Card title="Plivo Voice API" icon="phone" href="/docs/voice/api/calls">
    Make a call with the Plivo API.
  </Card>

  <Card title="Plivo Number Lookup API" icon="search" href="/docs/lookup/overview">
    Look up carrier and line-type details for a number.
  </Card>
</CardGroup>