Plugins and Side Channels

Agentix plugins extend the runtime in two different ways:

expose importable Python functions that callers run with sandbox.remote
open side-channel Socket.IO namespaces for events between host and sandbox

The runtime server stays generic. It does not know plugin event names or payload schemas; it only forwards namespace traffic between the host client and the worker process. Agentix Runtime extension model

The Three Core Systems

Agentix core owns three reserved Socket.IO namespaces:

Namespace	System	User-facing API	Extension point
`/rpc`	RPC	`await sandbox.remote(fn, args, *kwargs)`	expose a normal importable Python callable
`/log`	logging	stdlib `logging` in sandbox code	configure host logging handlers, levels, and formatters
`/trace`	tracing	`agentix.trace.trace(...)`, `agentix.trace.span(...)`	register `agentix.trace.Processor` implementations

Plugins must not claim these namespaces. A plugin that needs its own event protocol uses its own namespace, conventionally /<package-name>.

RPC: Extend With Callables

The /rpc namespace is the remote-call protocol. Users extend it by installing functions into the bundle, not by subclassing a base class:

# app.py, installed in the bundle
async def run(input: str) -> dict:
    return {"output": input.upper()}

The host calls the function object:

from app import run

result = await sandbox.remote(run, input="hello")

The sandbox serializes the target as fn.__module__ + "::" + fn.__qualname__, pickles args and kwargs, and the worker imports the same callable inside the sandbox.

Logging: Extend With stdlib logging

The /log namespace is the logging bridge. Sandbox code uses standard Python logging:

import logging

logger = logging.getLogger(__name__)

async def run() -> None:
    logger.info("starting rollout")

At worker boot, Agentix installs a root logging.Handler that forwards LogRecord data over /log. The sandbox automatically registers the host consumer and replays those records into the host logging tree. Beyond stdlib records, the worker also captures the process’s raw stdout and stderr — print(), subprocess output, C-extension writes — and replays each line over the same /log namespace under the logger names agentix.sandbox.stdout and agentix.sandbox.stderr. The identical output is also appended to a durable $AGENTIX_LOG_DIR/sandbox-<worker-id>.log (default /tmp/agentix; set the variable empty to disable), so output that outlives a dropped connection is still recoverable inside the sandbox. Users customize logging with normal logging configuration on the host:

import logging
from agentix.utils.log import configure_logging

configure_logging(default_context="host")
logging.getLogger("my_eval").setLevel(logging.INFO)

Do not register your own /log namespace. If a plugin needs structured events that are not log records, give the plugin its own namespace.

Tracing: Extend With Processors

The /trace namespace is the trace bridge. User code creates traces and spans:

from agentix import trace

async def run() -> None:
    with trace.trace("eval"):
        with trace.span("agent.step", model="claude") as span:
            span.add_event("first_token")

At worker boot, Agentix installs an internal trace.Processor that forwards trace and span lifecycle events over /trace. The sandbox automatically registers the host consumer, which replays those events into the host trace provider. Users extend tracing by registering processors:

from agentix import trace

class CaptureProcessor(trace.Processor):
    def on_trace_start(self, t: trace.Trace) -> None:
        ...

    def on_trace_end(self, t: trace.Trace) -> None:
        ...

    def on_span_start(self, s: trace.Span) -> None:
        ...

    def on_span_end(self, s: trace.Span) -> None:
        ...

    def force_flush(self) -> None:
        ...

    def shutdown(self) -> None:
        ...

trace.add_processor(CaptureProcessor())

A processor registered in the host process receives host-local spans and spans replayed from sandbox /trace events. A processor registered inside sandbox code receives sandbox-local spans. Do not register your own /trace namespace. If a plugin needs a different event model, use a plugin namespace and optionally convert those events into spans through a trace.Processor.

Choosing: Callables vs. Namespaces

Two ways to expose sandbox behavior — pick by data-flow shape:

Callable (sandbox.remote(fn, ...)) — one call in, one return value out, after the work finishes. No data flows back mid-execution. This is the default; bash run, file upload/download, and agent/scorer wrappers are all callables.
Callable returning AsyncIterator[T] — progressive results streamed to the host as they happen, host → sandbox only. bash.run_stream yields BashStdout / BashStderr / BashExit events this way.
Namespace — host and sandbox exchange data during execution (bidirectional), or the plugin bridges an external service the sandbox must reach through the host. abridge uses a namespace: sandbox code forwards an LLM request to the host, the host calls the real upstream, and the reply comes back on the same namespace — all while the agent keeps running in the sandbox.

Rule of thumb: reach for a callable first. Use a namespace only when you need a persistent, bidirectional channel; it costs an extra class on each side.

Plugin Namespaces

A plugin namespace has two optional halves:

a sandbox-side agentix.Namespace, registered inside the worker
a host-side agentix.AsyncClientNamespace, registered on the live sandbox

The sandbox side emits events or handles host requests:

import agentix

class MyService(agentix.Namespace):
    namespace = "/my-plugin"

    async def on_configure(self, payload):
        ...

agentix.register_namespace(MyService())

The host side receives events or replies to sandbox requests:

import agentix
from agentix.provider.docker import DockerProvider, DockerProviderConfig

class MyHost(agentix.AsyncClientNamespace):
    def __init__(self):
        super().__init__("/my-plugin")

    async def on_record(self, payload):
        ...

provider = DockerProvider(DockerProviderConfig(...))

async with provider.session(SandboxConfig(image=..., bundle=...)) as sandbox:
    sandbox.register_namespace(MyHost())
    result = await sandbox.remote(run, input="hello")

sandbox.register_namespace(...) must run before the first remote call, because the Socket.IO connection plan is fixed at connect time.

Round-trip Requests

When the sandbox needs an answer from the host mid-run, the sandbox side calls await self.request("fetch", body). It emits the request with a generated request_id and waits for the host to reply on fetch:result (success) or fetch:error (failure). On the host, wrap the handler with request_handler so the envelope, the reply event name, and error replies are handled for you:

from agentix import AsyncClientNamespace, request_handler

class MyHost(AsyncClientNamespace):
    def __init__(self):
        super().__init__("/my-plugin")

    @request_handler("fetch")
    async def on_fetch(self, body):
        return await call_upstream(body)   # return value → fetch:result

The wrapped coroutine receives the unwrapped request body and returns the reply value; a raised exception becomes a fetch:error reply carrying {"type", "message"} — the shape Namespace.request re-raises as RemoteSioError. Without the decorator you must pull request_id out of the envelope yourself and emit the exact fetch:result / fetch:error event by hand; a typo or a forgotten reply hangs the sandbox until its request timeout.

What the Server Does

The runtime server is namespace-opaque: When the worker registers a namespace, it sends sio_open to the server. The server then registers a matching Socket.IO forwarder. This is why plugins do not need runtime-server patches for new event protocols.

Packaging a Plugin

A plugin package can contribute any combination of:

importable functions that callers invoke with sandbox.remote
sandbox-side namespaces registered by code running in the worker
host-side namespace handlers registered on the live sandbox
sandbox providers through the agentix.provider entry-point group
system dependency closures through the agentix.nix entry-point group

Keep these boundaries separate. Remote calls are the main RPC system; /log and /trace are core side channels; plugin-specific protocols belong on the plugin’s own namespace.

Start

Concepts

How-to

Reference

Contribute

Plugins and Side Channels

The Three Core Systems

RPC: Extend With Callables

Logging: Extend With stdlib logging

Tracing: Extend With Processors

Choosing: Callables vs. Namespaces

Plugin Namespaces

Round-trip Requests

What the Server Does

Packaging a Plugin

​The Three Core Systems

​RPC: Extend With Callables

​Logging: Extend With stdlib logging

​Tracing: Extend With Processors

​Choosing: Callables vs. Namespaces

​Plugin Namespaces

​Round-trip Requests

​What the Server Does

​Packaging a Plugin

The Three Core Systems

RPC: Extend With Callables

Logging: Extend With stdlib logging

Tracing: Extend With Processors

Choosing: Callables vs. Namespaces

Plugin Namespaces

Round-trip Requests

What the Server Does

Packaging a Plugin