Compute Provider Plugins

Ship your own compute backend as a separate package

Ship a compute backend in its own package and register it under the praisonai.compute entry-point group — run_on=, compute=, and tools_run_on= pick it up with no change to the main repo.

Diagram

Quick Start

Declare the entry point

Point the praisonai.compute group at a class in your package.

toml

# pyproject.toml — in your plugin package
[project.entry-points."praisonai.compute"]
runpod = "praisonai_compute_runpod:RunpodCompute"

Implement the protocol

Satisfy ComputeProviderProtocol. Set an optional display_name for a friendly phrase.

python

# praisonai_compute_runpod/__init__.py

class RunpodCompute:
    display_name = "a Runpod cloud sandbox"  # optional, used in explanations

    async def provision(self, config):
        ...  # start an instance, return an InstanceInfo

    async def execute(self, instance_id, command, timeout=300):
        ...  # run a command, return {"stdout", "stderr", "exit_code"}

    async def shutdown(self, instance_id):
        ...  # tear the instance down

    @property
    def is_available(self):
        return True  # credentials present, SDK importable, etc.

Use it like a built-in

After pip install, the name resolves anywhere a compute place is accepted.

python

from praisonaiagents import Agent

agent = Agent(name="runner", instructions="Run code", tools_run_on="runpod")
agent.start("Print the Python version")

How It Works

Providers are discovered from the entry-point group and loaded on demand — only when a caller names one.

Diagram

Behaviour	What happens
Discovery	Names come from `importlib.metadata.entry_points(group="praisonai.compute")` — no file in the main repo changes.
Friendly phrase	A `display_name` class attribute is used in `where_does_it_run()` and `repr(agent)`; without it, the bare name is shown.
Failure isolation	Providers load lazily, so a broken plugin fails only for the caller that names it — everyone else is unaffected.
`managed ps`	Derives its list from the registry, so a contributed place is listed and stopped automatically — no extra wiring.

Protocol Reference

Implement these on your provider class. display_name is optional; the rest are required.

Member	Kind	Purpose
`provision(config)`	`async`	Start one instance and return its `InstanceInfo`.
`execute(instance_id, command, timeout=300)`	`async`	Run a command; return `{"stdout", "stderr", "exit_code"}`.
`shutdown(instance_id)`	`async`	Tear the instance down.
`is_available`	property	`True` when the backend can run (credentials, SDK, daemon).
`display_name`	class attr	Optional phrase used in explanations instead of the bare name.

Best Practices

Set display_name for readable explanations

A bare provider name reads awkwardly in where_does_it_run(). Set display_name = "a Runpod cloud sandbox" on the class so the phrase reads naturally everywhere the place is described.

Make is_available cheap and honest

is_available is checked before your provider runs. Return False when a required key or SDK is missing rather than raising — the caller gets a clear “unavailable” instead of a stack trace.

Keep imports lazy

Import heavy SDK dependencies inside your methods, not at module top level. Providers load on demand, so a missing optional dependency should fail only when the provider is actually used.

Ship the extra alongside the entry point

Declare an optional install extra for your provider’s SDK so users can pip install your-package[runpod]. This keeps the base install light and the failure mode obvious.

Placement

Where the whole agent, its tools, and its code calls run.

Sandbox Backends

The sibling praisonai.sandbox entry-point group for Agent(sandbox=…).

Managed Backend Plugins

Reclaim Stray Sandboxes

managed ps lists contributed places automatically.

Compute Provider Plugins

Quick Start

How It Works

Protocol Reference

Best Practices

Related