Factory & Backends

Backend Factory

backends

Backend registry and factory.

create_backend(name, *, harness, **kwargs)

Create a backend instance by name.

Parameters:

Name	Type	Description	Default
name	str	Backend name ("podman" or "openshell").	required
harness	Harness	Agent harness instance.	required
**kwargs	Any	Backend-specific arguments (workdir, image, policy, timeout, etc.).	{}

Returns:

Type	Description
Backend	A Backend instance.

Source code in src/agentic_ci/backends/__init__.py

def create_backend(name: str, *, harness: Harness, **kwargs: Any) -> Backend:
    """Create a backend instance by name.

    Args:
        name: Backend name ("podman" or "openshell").
        harness: Agent harness instance.
        **kwargs: Backend-specific arguments (workdir, image, policy, timeout, etc.).

    Returns:
        A Backend instance.
    """
    if name == "local":
        return LocalBackend(
            workdir=kwargs.get("workdir", "."),
            extra_env=kwargs.get("extra_env"),
            harness=harness,
        )
    elif name == "podman":
        return PodmanBackend(
            workdir=kwargs.get("workdir", "."),
            image=kwargs.get("image"),
            timeout=kwargs.get("timeout", 1200),
            extra_env=kwargs.get("extra_env"),
            harness=harness,
        )
    elif name == "openshell":
        return OpenShellBackend(
            workdir=kwargs.get("workdir", "."),
            image=kwargs.get("image"),
            policy=kwargs.get("policy"),
            extra_env=kwargs.get("extra_env"),
            approval_mode=kwargs.get("approval_mode"),
            harness=harness,
        )
    else:
        raise ValueError(f"Unknown backend: {name!r}. Choose 'local', 'podman', or 'openshell'.")

Local Backend

local

Local (direct execution) backend for agentic-ci.

LocalBackend(workdir='.', extra_env=None, *, harness)

Bases: Backend

Runs an AI agent directly in the local environment.

No container or sandbox — the agent binary must already be installed and accessible on PATH. Useful when agentic-ci is running inside an existing CI container (e.g. Prow) where an extra isolation layer is unnecessary.

Source code in src/agentic_ci/backends/local.py

def __init__(self, workdir=".", extra_env=None, *, harness: Harness):
    super().__init__(workdir=workdir, image=None, harness=harness)
    self._extra_env = extra_env or {}

Podman Backend

podman

Podman container backend for agentic-ci.

PodmanBackend(workdir='.', image=None, timeout=1200, extra_env=None, *, harness)

Bases: Backend

Runs an AI agent inside a persistent Podman container.

setup() creates a long-running detached container. run() execs the agent inside it. stop() tears it down. The work directory is mounted into the container and gcloud credentials are mounted read-only.

Source code in src/agentic_ci/backends/podman.py

def __init__(
    self,
    workdir=".",
    image=None,
    timeout=1200,
    extra_env=None,
    *,
    harness: Harness,
):
    super().__init__(workdir=workdir, image=image, harness=harness)
    self.timeout = timeout
    self._config_dir = None
    self._extra_env = extra_env or {}