Skip to main content

Runkite governance helper

A standard-library-only Python client for POST /governance/decide and GET /governance/actions/{id} on your self-hosted Runkite plane. It does not depend on the runner package or an agent framework.

Use this helper when an existing Python service keeps its agent loop and needs an allow, deny or pending answer before a tool call. It works with ordinary application code; Microsoft function middleware is an optional integration, not a requirement. A managed runkite-runner instead executes assignments dispatched by the control plane and does not require this helper.

This helper has its own distribution, separate from runkite-runner, first published in Runkite v0.8.0. Published v0.7.0 did not include it. Install a verified registry release with:

python -m pip install runkite-governance

For source that has not been published, install from a checkout:

python -m pip install ./python/runkite_governance

The runtime requires Python 3.11 or newer. Installing a managed runner does not install this decision-only helper.

Configure the plane and application

The administrator configures authentication, tenant-scoped grants, optional human approval and durable SQL review storage on the control plane. The application installs this helper and supplies its plane URL and server-side API key. Follow the operator and application setup guide or the repository handbook for the complete setup, Admin review flow and troubleshooting.

Import the same module after a registry or checkout installation:

import os
from runkite_governance import GovernanceClient

governance = GovernanceClient(
    os.environ["RUNKITE_HTTP_URL"],
    api_key=os.environ["RUNKITE_API_KEY"],
    timeout_ms=10_000,
)
decision = governance.decide(
    agent_id="notes-app",
    connector="workspace",
    tool="createNote",
    args={"title": "Release notes", "body": "A draft"},
    run_id="stable-app-turn-and-tool-call-id",
)

Your application executes after allow, refuses after deny, and persists the action ID and exact original arguments after pending. On a later application request, use governance.action(action_id) and execute only after approved. Rejected or consumed actions must not execute. Implement idempotency in the application's database: GET does not consume approval.

If decide, action or resolve raises, stop the operation without executing the tool. HTTP/protocol and deadline failures can raise GovernanceError; network failures can also propagate standard-library transport exceptions. Do not treat an exception, an unavailable plane or a timeout as allow. Handle the failure at the application's request boundary and retain any saved pending operation for an explicit later continuation.

resolve(...) performs a bounded wait and returns an allow/deny outcome. Its deadline covers the initial decision and every poll. decide and action accept timeout_ms and a threading.Event as cancelled. Cancellation stops the caller promptly. Blocking standard-library I/O unwinds separately with a socket timeout and response-chunk checks; a bounded shared worker pool prevents unlimited abandoned resolver/socket threads. Do not hold a serverless request open for long operator approval.

Use a server-side key with governance:decide. Tenant identity comes from that key. The caller retains its model loop and tool execution. This path creates no Runkite thread or run and does not apply run kill switches, break-glass or spend caps. It is separate from the deliberately deferred full client SDK.

Optional Microsoft Agent Framework middleware

For a verified registry release, install the optional middleware with:

python -m pip install 'runkite-governance[agent-framework]'

For unpublished source, install the extra from a checkout:

python -m pip install './python/runkite_governance[agent-framework]'

The extra pins the tested framework core; model-provider packages remain application choices.

Import GovernanceFunctionMiddleware, GovernedFunction, GovernanceBlockedError and PendingInvocation from runkite_governance.agent_framework. Register exact local FunctionTool objects, server-owned policy identities and an application operation-ID callback. Install the guard last, after argument repair. It snapshots JSON arguments and Python defaults, decides once, and reaches native execution only after allow. Deny and pending stop the agent with a native MiddlewareFailure; an optional async on_pending callback persists the exact frozen proposal first.

The app owns pending continuation and execution idempotency. Rich Python types, coercing validators and provider-executed tools are outside this adapter's scope. See the framework example for a durable application transaction, offline streaming and non-streaming tests, and supported argument constraints. Execution retains native mutable containers; the app must not mutate invocation arguments after authorization. Importing the base client does not import the optional framework. This extra is not a runner adapter and creates no run.

License: Apache-2.0. See LICENSE and NOTICE. Third-party dependencies retain their own licenses.

Metadata

Release files for runkite-governance 0.9.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for runkite-governance 0.9.0
File Size Uploaded Provenance Actions
runkite_governance-0.9.0.tar.gz 16.5 kB With provenance Details for runkite_governance-0.9.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for runkite-governance 0.9.0
File Interpreter ABI Platform Actions
runkite_governance-0.9.0-py3-none-any.whl Python 3 none any Details for runkite_governance-0.9.0-py3-none-any.whl

Total release size: 32.3 kB

Release files / runkite_governance-0.9.0.tar.gz

Download URL runkite_governance-0.9.0.tar.gz
Size 16.5 kB
Tags Source
SHA-256 checksum
How to use checksums
6f8478b7816bd444abb424fff8eb7aa28be6da5a3c9814fe61c6eba40f5d3149
BLAKE2b-256 checksum
How to use checksums
f4ba12294c52b354b27ad295fa353238f281fd638c395343dbc4c83a19e0698c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / runkite_governance-0.9.0-py3-none-any.whl

Download URL runkite_governance-0.9.0-py3-none-any.whl
Size 15.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
01f23e29d474cb7a4b92cd71f155bb72031c6b8aea36c2a4a1750d08f962ad43
BLAKE2b-256 checksum
How to use checksums
e3c540652d91837a261109c865ceb3d5715cf09983bd8a284d7d4a1ad490d072
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for runkite-governance 0.9.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for runkite_governance-0.9.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.9.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page