How to Add ATXP to Agno

Agno (formerly Phidata) is one of the cleanest Python agent frameworks available. Its tool dispatch is minimal, its structured output model is genuinely useful, and its Team abstraction handles multi-agent coordination without a lot of ceremony. For agno phidata agent payments, that clean architecture is also why ATXP wires in without friction — Agno tools are plain Python callables, so ATXP-backed tools look identical to anything else in the framework.

The problem this guide solves: the moment your Agno agent starts calling paid external APIs — web search, data enrichment, email, image generation — you have a credential management and spend tracking problem that Agno correctly doesn’t try to solve. You end up with a .env file full of service-specific keys, separate billing dashboards, and no unified view of what the agent actually spent.

ATXP is a single credential that covers 14+ paid tools, with session-scoped spending limits and per-call receipts. Here’s how to add it to Agno in about fifteen minutes.

What Agno Gets Right (and Where It Leaves a Gap)

Agno’s design philosophy is minimal overhead: define your tools as typed Python functions, pass them to an Agent, run. The framework introspects your functions to build the JSON schema the LLM sees, handles tool dispatch, and parses results. Its Pydantic integration means you can define structured response_model types that the agent fills in — typed receipts, summaries, cost breakdowns, whatever your downstream logic needs.

What Agno doesn’t handle: paying for the tools your agent calls. That’s a correct boundary. But if your agent calls a web search API, a page fetcher, or any paid service, you’re managing API keys and billing outside the framework — and as your tool count grows, that overhead compounds. The real cost of managing multiple AI APIs yourself isn’t just money; it’s the operational surface area.

ATXP fills that gap. One API key replaces N service credentials. One balance, one invoice, one place to set spend limits.

How ATXP Maps Onto Agno’s Tool Model

Without ATXP	With ATXP
One API key per paid tool	Single `ATXP_API_KEY`
Separate billing per service	One balance, one invoice
No per-call spend tracking	Structured credit receipt per call
Budget limits require custom middleware	Session tokens with hard caps
Credential sprawl across `.env`	One secret to rotate
Service-specific error handling	Unified `atxp` exception hierarchy

The structured output advantage is specific to Agno: because the framework returns typed Pydantic objects, you can include a cost_credits field in your tool return types and get per-call attribution baked into the agent’s final output — no separate logging layer required.

Installation

pip install agno atxp

Set credentials:

export ATXP_API_KEY="your-atxp-api-key"
export OPENAI_API_KEY="your-openai-key"

Get your ATXP API key at atxp.ai.

Setting Up Agno Agent Payments: The Basic Pattern

Here’s a research agent that calls ATXP’s web search and captures cost per call in a structured output:

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from pydantic import BaseModel
import atxp
import os

client = atxp.Client(api_key=os.environ["ATXP_API_KEY"])

class SearchResult(BaseModel):
    query: str
    summary: str
    sources: list[str]
    cost_credits: float

class ResearchOutput(BaseModel):
    topic: str
    findings: list[SearchResult]
    total_cost_credits: float

def web_search(query: str) -> SearchResult:
    """Search the web for current information on a topic."""
    result = client.search.web(query=query)
    return SearchResult(
        query=query,
        summary=result.summary,
        sources=result.sources,
        cost_credits=result.credits_used,
    )

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    tools=[web_search],
    response_model=ResearchOutput,
    instructions=[
        "Research the given topic thoroughly.",
        "Include source URLs for all claims.",
        "Sum credits used across all search calls in total_cost_credits.",
    ],
)

response = agent.run("Research the current state of AI agent payment protocols")
output = response.content
print(f"Total spend: {output.total_cost_credits} credits")
for finding in output.findings:
    print(f"  {finding.query}: {finding.cost_credits} credits")

The cost_credits field propagates through Agno’s structured output pipeline without any custom instrumentation. By the time the agent finishes, you have a typed receipt.

How to Set Spending Limits on Agno Tool Calls

Spending limits belong at the ATXP layer, not in your agent code. ATXP session tokens carry a hard budget cap that applies to every API call made with that token:

# Create a session-scoped token with a hard cap
session = client.sessions.create(
    budget_credits=50,           # max credits this agent can spend
    on_budget_exceeded="reject", # raise BudgetExceededError at the limit
)

session_client = atxp.Client(api_key=session.token)

def web_search(query: str) -> SearchResult:
    """Search the web for current information."""
    result = session_client.search.web(query=query)
    return SearchResult(
        query=query,
        summary=result.summary,
        sources=result.sources,
        cost_credits=result.credits_used,
    )

When the agent hits the cap mid-run, ATXP raises atxp.BudgetExceededError on the blocked call. Agno surfaces this as a tool error in the LLM’s context. A well-prompted agent handles it gracefully — summarizing what it found before the limit rather than crashing. You can also use on_budget_exceeded="notify" to receive a webhook and let the agent continue running while you’re alerted.

This is the model described in how ATXP’s IOU system caps agent spending: the budget is a hard wall provisioned at the infrastructure level, not a soft limit you implement yourself.

Budget Isolation in Agno Teams

Agno’s Team abstraction coordinates multiple specialized agents. The budget question becomes more interesting here: shared pool across the team, or per-agent caps?

ATXP session tokens answer this cleanly — provision one token per agent, each with its own budget:

from agno.team import Team
from agno.agent import Agent
from agno.models.openai import OpenAIChat
import atxp, os

main_client = atxp.Client(api_key=os.environ["ATXP_API_KEY"])

def make_session(budget: int) -> atxp.Client:
    session = main_client.sessions.create(
        budget_credits=budget,
        on_budget_exceeded="reject",
    )
    return atxp.Client(api_key=session.token)

research_client = make_session(100)  # researcher gets 100 credits
content_client = make_session(30)    # writer gets 30 credits

def research_search(query: str) -> dict:
    """Perform a web search."""
    result = research_client.search.web(query=query)
    return {"summary": result.summary, "credits_used": result.credits_used}

def fetch_page(url: str) -> dict:
    """Fetch and parse a web page."""
    result = content_client.web.fetch(url=url)
    return {"content": result.text, "credits_used": result.credits_used}

researcher = Agent(
    name="Researcher",
    role="Find and synthesize information from the web",
    model=OpenAIChat(id="gpt-4o"),
    tools=[research_search],
)

writer = Agent(
    name="Writer",
    role="Draft content based on research findings",
    model=OpenAIChat(id="gpt-4o-mini"),
    tools=[fetch_page],
)

team = Team(
    name="Content Team",
    agents=[researcher, writer],
    mode="coordinate",
)

response = team.run("Write a briefing on the latest AI agent frameworks")

If the researcher hits its 100-credit cap, the writer’s 30-credit session is unaffected. This is budget isolation at the infrastructure level — no shared state, no application-layer accounting. It’s the same principle covered in the multi-agent system guide, applied specifically to Agno’s Team model.

When Does ATXP Make Sense for Your Agno Agent?

Not every Agno agent needs a payment layer. The honest breakdown:

Scenario	Use ATXP?	Reason
Agent calls 2+ paid external APIs	Yes	Credential consolidation alone is worth it
Multi-agent team with per-agent budgets	Yes	Session token isolation per agent
Agent calls only internal services	No	No external payment layer needed
Pure LLM orchestration, no tool calls	No	ATXP is for tool-call payments
Single paid API, simple use case	Maybe	Low friction to add early; saves refactor later
Production agent with audit requirements	Yes	Typed receipts per call, one billing account

The inflection point is roughly two paid tools. At one, you can manage a single credential directly. At two or more, you’re coordinating billing, keys, and rate limits across services — and that operational overhead grows faster than the tool count. According to Stripe’s 2026 developer survey, 61% of teams building production agents report credential management as a top-three integration pain point (Stripe Developer Report, Q1 2026).

ATXP Tools Available for Agno Agents

Each maps to a typed Python function in your agent’s tool list:

Web search — real-time results, cited sources
Web fetch — scrape and parse any URL
Image generation — Flux, DALL-E, Stable Diffusion
Email send/receive — full mailbox access for agents
SMS and voice — Twilio-backed, agent-controlled
X/Twitter search — real-time social and news data
100+ LLM models — route to any model without separate keys
Video and music generation — AI media creation

Every call from any tool appears as a line item in your ATXP dashboard with the agent identifier, tool name, credit cost, and timestamp. For Agno agents specifically, you can cross-reference this against the structured output your agent returned to get full end-to-end traceability.

Mid-Article: Connect Your Agent Now

If you’re already building with Agno, the fastest path forward is to register at atxp.ai, drop in one ATXP-backed tool, and verify the receipt in your dashboard before adding more. The credential consolidation pays off immediately; the spend tracking compounds from there.

Frequently Asked Questions

Does ATXP require changes to Agno’s core tool dispatch?

No. ATXP tools are standard Python callables with type annotations. Agno introspects them the same way it does any other tool — no subclassing, no hooks into Agno internals. You’re writing functions that call ATXP’s API instead of a service-specific endpoint.

Can I mix ATXP tools with non-ATXP tools in the same Agno agent?

Yes. You can have one tool calling ATXP for web search and another calling your internal database directly. Agno dispatches to both without distinction. ATXP only charges for calls that go through its API. There’s no requirement to route everything through ATXP.

How does ATXP handle credentials for services like email and SMS?

ATXP manages credentials for each underlying service. Your agent authenticates once to ATXP with your API key. ATXP uses its own credentials with the downstream service — Twilio, SendGrid, etc. Your agent never holds a service-specific key. This is the core security model: building an agent without API keys for the tool layer. The blast radius of a compromised agent credential is limited to your ATXP budget, not your entire Twilio account.

Does this work with Agno’s async support?

Yes. ATXP has an async Python client via atxp.AsyncClient. Replace synchronous calls with await async_client.search.web() and the pattern is identical. Agno’s async tool dispatch handles it without modification.

How does ATXP credit pricing compare to calling services directly?

ATXP passes through at cost with a small platform margin. For most tools, the convenience and consolidation justify the margin — especially when you factor in the engineering time to maintain separate integrations. See the three models for agent payments for a broader comparison of how agent payment models differ in practice.