OpenAI Agents SDK

Pavri integrates with the OpenAI Agents SDK through a guardrail hook that enforces runtime governance policies on tool calls.

One-Line Integration

from pavri import PavriConfig, secure

agent = build_openai_agent()
agent = secure(agent, PavriConfig(agent_name="my-agent", plugin="openai_agents"))

The secure() call attaches the Pavri runtime to the agent, registers it with the backend, and installs the enforcement hook.

Supported Versions

• OpenAI Agents SDK >=0.1.0
• Python >=3.12

How It Works

Plugin Detection

The OpenAIAgentsAdapter matches when either:

• You pass plugin="openai_agents" in the config
• The target object's module name contains "openai"

Hooks Attached

When the runtime has an active policy cache and telemetry emitter, secure() attaches the following hook:

Hook	Purpose
_pavri_guardrail	Evaluates policy before tool execution; raises PolicyDeniedError on denial

The hook is set as an attribute on the agent object via setattr.

Guardrail Enforcement

The _pavri_guardrail hook is called with the tool name before each tool execution:

# Internal flow — you do not call this directly
agent._pavri_guardrail("tool_name")

The hook calls enforce_policy(f"tool:{tool_name}", ctx) against the local policy cache. The evaluation respects the configured fail_mode:

• fail-open (default): If policy evaluation fails, the tool call is allowed.
• fail-closed: If policy evaluation fails, the tool call is denied.

When a policy rule matches with a deny, block, or throttle (over limit) action, the hook raises PolicyDeniedError:

from pavri.core.exceptions import PolicyDeniedError

try:
    result = await runner.run("user input")
except PolicyDeniedError as e:
    print(f"Blocked: {e.reason} (rule: {e.rule_id})")

The exception carries the full PolicyDecision with the matched rule ID, reason, and policy metadata.

Configuration

Key PavriConfig options for OpenAI Agents:

from pavri import PavriConfig

config = PavriConfig(
    agent_name="my-agent",
    plugin="openai_agents",
    api_key="fab_...",
    backend_url="https://pavri.example.com",
    org_id="org-acme",
    session_id="session-123",
    team="platform",
    environment="production",
    fail_mode="open",          # "open" or "closed"
    telemetry_mode="full",     # "full", "metadata-only", or "disabled"
)

Field	Default	Description
fail_mode	"open"	Whether to allow or deny when policy evaluation fails
telemetry_mode	"full"	Controls telemetry detail level
environment	"development"	Deployment environment tag
policy_sync.poll_interval_seconds	60	How often to poll for policy updates
policy_sync.stale_after_seconds	300	Policy staleness threshold

Graceful Degradation

If the Pavri runtime cannot build an enforcement context (for example, the backend is unreachable and no cached policy is available), the plugin skips hook installation entirely. The agent runs without Pavri enforcement. This is visible in the runtime status:

from pavri.core import get_runtime

runtime = get_runtime(agent)
status = runtime.status()
print(status.connected, status.policy_revision)

Troubleshooting

Agent runs but no policy enforcement

• Verify the backend is reachable and api_key is set.
• Check runtime.status().policy_revision — if 0, the SDK has no cached policy.
• The plugin requires both a policy cache and telemetry emitter. If either is missing, enforcement is silently skipped.

PolicyDeniedError raised unexpectedly

• Inspect the exception: e.decision contains the full PolicyDecision with the matched rule_id and reason.
• Check whether fail_mode="closed" is set — this denies on evaluation failure.
• Review policies in the dashboard under the agent's policy configuration.

Plugin not detected

• Pass plugin="openai_agents" explicitly in the config.
• Ensure the agent object's module includes "openai" in its path for auto-detection.

What's Deferred

The following capabilities are planned for Phase 2:

• Log forwarding from the OpenAI plugin (buffer, drain, envelope pipeline)
• Trace-link capture for OpenAI's native OTel tracing
• Input/output guardrail integration (beyond tool-level enforcement)
• Handoff monitoring for multi-agent setups