feat: add Northflank provider

[fr3fou]

Summary

Adds a Northflank provider integration behind the optional northflank extra.

This includes:

• agents.extensions.northflank.northflank_tools(): a curated tool namespace for operating Northflank resources from agents.
• agents.extensions.northflank.NorthflankShellExecutor: a ShellTool executor that runs commands inside a Northflank service container.
• agents.extensions.sandbox.northflank.NorthflankSandboxClient: a hosted sandbox provider backed by Northflank services.

Supported features

Northflank tools support:

• List/get projects and services.
• Create deployment services from external Docker images.
• Restart, pause, resume, scale, and wait for services.
• Run one-shot exec commands in service, job, and addon containers.
• Fetch and tail service logs.
• Fetch service metrics.
• Optional gated tools for secrets, volumes, domains, and deletes.

Mutating, exec, and destructive tools are marked with needs_approval=True. Delete, secret, volume, and domain tools are opt-in via northflank_tools(include_...).

The sandbox provider supports:

• Creating ephemeral Northflank deployment services from an image.
• Attaching to an existing Northflank service.
• Shell exec through the sandbox session interface.
• Workspace read/write.
• Workspace persist/hydrate via tar.
• Snapshot/resume state.
• Cleanup of services created by the client.
• Workspace persistence across stop/resume via either a Northflank volume (workspace_persistence="volume") or a tar embedded in session state (workspace_persistence="tar").

Usage

Install with the optional extra:

pip install "openai-agents[northflank]"

Use Northflank tools with an authenticated SDK client:

from northflank import AsyncApiClient

from agents import Agent, Runner
from agents.extensions.northflank import NorthflankCtx, northflank_tools

client = AsyncApiClient()

agent = Agent(
    name="northflank-ops",
    instructions="Help inspect and operate Northflank services.",
    tools=list(northflank_tools()),
)

result = await Runner.run(
    agent,
    "List the services in this project and summarize their status.",
    context=NorthflankCtx(client=client, project_id="my-project"),
)

Use the shell executor with ShellTool:

from northflank import AsyncApiClient

from agents import Agent, Runner, ShellTool
from agents.extensions.northflank import NorthflankCtx, NorthflankShellExecutor

client = AsyncApiClient()

agent = Agent(
    name="northflank-shell",
    tools=[
        ShellTool(
            executor=NorthflankShellExecutor(service_id="api"),
            needs_approval=True,
        )
    ],
)

result = await Runner.run(
    agent,
    "Check disk and memory usage in the service container.",
    context=NorthflankCtx(client=client, project_id="my-project"),
)

Use Northflank as a sandbox backend:

from northflank import AsyncApiClient

from agents import Runner
from agents.run import RunConfig
from agents.sandbox import SandboxAgent, SandboxRunConfig
from agents.extensions.sandbox.northflank import (
    NorthflankSandboxClient,
    NorthflankSandboxClientOptions,
)

client = AsyncApiClient()

agent = SandboxAgent(
    name="northflank-sandbox",
    instructions="Inspect the sandbox workspace and answer concisely.",
)

run_config = RunConfig(
    sandbox=SandboxRunConfig(
        client=NorthflankSandboxClient(client=client),
        options=NorthflankSandboxClientOptions(
            project_id="my-project",
            image_path="ubuntu:24.04",
            docker_command="sleep infinity",
        ),
    )
)

result = await Runner.run(agent, "What files are in the workspace?", run_config=run_config)

Workspace persistence

By default the sandbox workspace lives in the container filesystem and is dropped when the service is deleted. Two opt-in strategies let it survive stop/resume:

Volume mode — provisions a Northflank volume mounted at manifest.root, attached to the service. The volume survives stop/resume and is deleted by client.delete() if the client created it. Only valid with image_path (client-owned services).

NorthflankSandboxClientOptions(
    project_id="my-project",
    image_path="ubuntu:24.04",
    docker_command="sleep infinity",
    workspace_persistence="volume",
)

volume_spec defaults to a 5120 MiB nf-multi-rw volume in ReadWriteMany mode (5120 MiB is the smallest size Northflank accepts on that storage class). Override it to use a different size, storage class, or access mode:

NorthflankSandboxClientOptions(
    ...,
    workspace_persistence="volume",
    volume_spec={
        "storageSize": 20480,
        "accessMode": "ReadWriteOnce",
        "storageClassName": "nvme",
    },
)

Tar mode — at stop() the workspace is tarred via exec and embedded (base64) into the session state. On resume() the tar is uploaded and extracted back into the workspace.

NorthflankSandboxClientOptions(
    project_id="my-project",
    image_path="ubuntu:24.04",
    docker_command="sleep infinity",
    workspace_persistence="tar",
)

Examples

• Listing Northflank services with northflank_tools().
• Running a remote ShellTool against a Northflank service.
• Running a sandbox agent on Northflank.

Tests

Unit coverage for the Northflank tools, shell executor, and sandbox client/session behavior.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c0dab526df

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Update the lockfile for the new extra

This adds the northflank optional dependency, but the commit does not update uv.lock, while CI installs from the frozen lock (UV_FROZEN=1 + make sync/uv sync --all-extras). With the current lock the package is not installed, so the new Northflank tests that import northflank at collection time fail with ModuleNotFoundError; please regenerate and commit the lockfile entry for this extra.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Do not exclude Northflank from the 3.14 test job

The dependency is guarded with python_version < '3.14', but the test workflow runs make sync/make tests on Python 3.14 (.github/workflows/tests.yml matrix includes 3.14). On that job --all-extras still omits northflank, while the new tests import northflank and agents.extensions.sandbox.northflank unconditionally during collection, so the 3.14 CI leg will fail unless the dependency is available there or those tests are skipped when it is not.

Useful? React with 👍 / 👎.