Agno - Plivo

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
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.

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:

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:

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:

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:

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.

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.

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.

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.
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.

Runnable examples

Clone-and-run Agno agents built on the Plivo tools.

Agno cookbook example

The Plivo tools example in the Agno cookbook.

Agno PlivoTools reference

Agno’s reference for the Plivo toolkit.

Plivo Messages API

Send an SMS with the Plivo API.

Plivo Voice API

Make a call with the Plivo API.

Plivo Number Lookup API

Look up carrier and line-type details for a number.

​Prerequisites

​Quick start

​Available tools

​Register a subset of tools

​Troubleshooting

​Related

Runnable examples

Agno cookbook example

Agno PlivoTools reference

Plivo Messages API

Plivo Voice API

Plivo Number Lookup API

Prerequisites

Quick start

Available tools

Register a subset of tools

Troubleshooting

Related