Tool Registry Proxy

Discover and call hundreds of third-party API endpoints through one token, with vendor credentials injected server-side

The registry proxy connector lets an agent discover and call a large catalogue of third-party API endpoints (SEO, enrichment, social data, scraping, ads) through a single token — vendor credentials are injected server-side by the registry, so the agent never holds keys.

Quick Start

1. Install and configure

   pip install 'praisonai-tools[registry-proxy]'
   export TOOL_PROXY_URL=http://127.0.0.1:18790   # your hosted or self-hosted registry
   export TOOL_PROXY_TOKEN=your-token
   export TOOL_PROXY_AUTH_HEADER=X-Treg-Token      # treg wire format; omit for Bearer

2. Give the three functions to an agent

   from praisonaiagents import Agent
   from praisonai_tools.registry_proxy import registry_search, registry_describe, registry_call
   
   agent = Agent(
       instructions="Find and use external APIs via the tool registry.",
       tools=[registry_search, registry_describe, registry_call],
   )
   agent.start("Enrich the person behind alice@example.com and summarise who they are.")

The agent searches the catalogue, describes a matching endpoint, then calls it — one token, no vendor keys in the agent.

How It Works

The connector exposes three functions over the registry’s plain-HTTP surface.

The registry HTTP routes the connector talks to:

Self-Hosting the Registry

treg is an external, self-hostable tool registry. These are the exact steps to stand up a local registry for testing.

1. Clone treg

   git clone https://github.com/superdesigndev/treg
   cd treg

2. Install (Python 3.12–3.13)

   # If your default python is older, use uv:
   uv sync --extra server --python 3.13

3. Boot the server

   # Default port 18790. Optionally point it at a sqlite file:
   TREG_DATABASE_URL="sqlite+aiosqlite:////tmp/treg.db" .venv/bin/python -m treg
   # server is now on http://127.0.0.1:18790

4. Mint an API token

   curl -X POST http://127.0.0.1:18790/users \
     -H 'Content-Type: application/json' \
     -d '{"email": "you@example.com"}'
   # -> {"token": "..."}  — save this

Auth on all authenticated routes is the raw token in the X-Treg-Token header — set TOOL_PROXY_AUTH_HEADER=X-Treg-Token so the connector sends the raw token instead of Bearer {token}.

The Three Functions

Each function is an agent tool that defaults to the TOOL_PROXY_URL / TOOL_PROXY_TOKEN environment variables.

registry_search

Free capability search returning catalogue matches for a natural-language query.

from praisonai_tools.registry_proxy import registry_search

registry_search("enrich a person from an email address")
# {'query': ..., 'count': 2, 'results': [{'id': 'hunter.x.combined', ...}, ...]}

registry_describe

Free read returning an endpoint’s parameters, HTTP method, price-per-call and an example response.

from praisonai_tools.registry_proxy import registry_describe

registry_describe("diffbot.people.enrich")
# {'endpoint': {'id': ..., 'method': 'GET',
#   'cost': {'value': 25, 'currency': 'credit', 'usd': 0.0299}, ...}}

registry_call

Paid invoke. The registry injects the upstream vendor credential server-side. The HTTP method is auto-derived from the describe doc; GET params are sent as the query string, POST/PUT as a JSON body.

from praisonai_tools.registry_proxy import registry_call

registry_call("diffbot.people.enrich", params={"type": "person", "email": "a@b.co"})
# method auto-derived as GET from the describe doc; params sent as query string

Configuration Options

Configure the connector with environment variables (zero-code) or per-call keyword arguments.

Environment Variables

Constructor / Per-Call Options

RegistryProxyTool accepts these options; the same names work as optional keyword arguments on registry_search, registry_describe and registry_call.

Spend Guards

registry_call accepts optional budget guards that deny and report a call as a tool-result error before any money is spent.

from praisonai_tools.registry_proxy import registry_call

registry_call(
    "diffbot.people.enrich",
    params={"type": "person", "email": "a@b.co"},
    max_cost_per_call=0.05,   # never pay more than 5 cents for one call
    max_session_spend=1.00,   # hard $1 ceiling for the whole session
)
# over budget -> {'error': 'Denied: price per call 0.0299 exceeds max_cost_per_call ...'}

• Per-call price is read from registry_describe, so guards work without vendor-specific configuration.
• Guards fail closed: if a budget is set but the price cannot be read (or is non-finite/negative), the call is denied.
• max_session_spend persists across separate registry_call invocations in the same process, scoped per (proxy_url, token) so distinct accounts never share a budget.

Security Model

The connector is designed so a prompt-injected agent cannot leak the proxy token or spend uncontrolled money.

Examples

Direct three-step flow (no agent)

from praisonai_tools.registry_proxy import registry_search, registry_describe, registry_call

hits = registry_search("enrich a person from an email address")
# {'query': ..., 'count': 2, 'results': [{'id': 'hunter.x.combined', ...}, ...]}

doc = registry_describe("diffbot.people.enrich")
# {'endpoint': {'id': ..., 'method': 'GET',
#   'cost': {'value': 25, 'currency': 'credit', 'usd': 0.0299}, ...}}

result = registry_call("diffbot.people.enrich", params={"type": "person", "email": "a@b.co"})
# method auto-derived as GET from the describe doc; params sent as query string

Explicit method and class form

from praisonai_tools.registry_proxy import RegistryProxyTool

t = RegistryProxyTool(auth_header="X-Treg-Token", max_session_spend=2.0)
t.run(action="search", query="weather forecast")
t.run(action="describe", tool_id="{tool-id}")
t.run(action="call", tool_id="{tool-id}", params={"q": "London"}, method="GET")

Different registry wire-format (non-treg deployment)

from praisonai_tools.registry_proxy import RegistryProxyTool

t = RegistryProxyTool(
    auth_header="Authorization",              # Bearer token style
    describe_path="/api/v1/tools/{tool_id}",  # custom describe route
)

Troubleshooting

Related