SDK Reference

Complete reference for the PhronEdge Python SDK.

Current version: 2.4.6

Installation

pip install phronedge

Requires Python 3.9 or higher. Works with any framework. No additional dependencies.

PhronEdge class

from phronedge import PhronEdge

pe = PhronEdge(
    api_key=None,         # reads PHRONEDGE_API_KEY env var if not set
    gateway_url=None,     # reads PHRONEDGE_GATEWAY_URL or defaults to https://api.phronedge.com/api/v1
    timeout=30,           # request timeout in seconds
    raise_on_block=False, # if True, blocked calls raise ToolBlocked instead of returning a dict
    agent_id=None,        # agent ID to fetch credential for (one key, many agents)
)

Constructor parameters

Environment variables

Multi-agent tenants

When one API key owns multiple agents, pass agent_id explicitly so the SDK fetches the right credential:

pe_fraud = PhronEdge(agent_id="fraud-analyst")
pe_kyc   = PhronEdge(agent_id="kyc-verifier")

Without agent_id, the SDK fetches the first available credential. This is fine for single-agent tenants but unreliable with multiple agents.

govern() decorator

@pe.govern(tool_name, action="execute", jurisdiction=None, mcp=None, delegates=None)
def my_tool(arg1, arg2):
    ...

Parameters

Decorator order

When combining with framework decorators, PhronEdge must be the inner decorator:

# LangGraph / LangChain
@tool
@pe.govern("my_tool", action="read")
def my_tool(): ...

# CrewAI
@tool("my_tool")
@pe.govern("my_tool", action="read")
def my_tool(): ...

# OpenAI Agents
@function_tool
@pe.govern("my_tool", action="read")
def my_tool(): ...

# LlamaIndex (no framework decorator needed)
@pe.govern("my_tool", action="read")
def my_tool(): ...

# Google ADK (no framework decorator needed)
@pe.govern("my_tool", action="read")
def my_tool(): ...

Behavior on block

raise_on_block=False (default)

The function body does not execute. A dict is returned:

{
    "blocked": True,
    "reason": "Action 'delete' not permitted on tool 'claim_lookup'. Allowed: read, execute",
    "checkpoint": "judge",
    "regulation": "EU AI Act Art. 14",
    "retry": True,
    "message": "Tool call blocked by PhronEdge governance."
}

This is recommended for agentic frameworks where the LLM needs to see the block reason and adapt its next action.

raise_on_block=True

The function body does not execute. A ToolBlocked (or AgentTerminated) exception is raised:

from phronedge import PhronEdge, GovernanceError, ToolBlocked, AgentTerminated

pe = PhronEdge(raise_on_block=True)

try:
    result = my_tool("arg")
except AgentTerminated as e:
    # Agent has been permanently killed. Not retryable.
    log_kill_event(e)
except ToolBlocked as e:
    print(e.reason)       # "Action 'delete' not permitted..."
    print(e.checkpoint)   # "judge"
    print(e.regulation)   # "EU AI Act Art. 14"
    print(e.retry)        # True
    print(e.blocked)      # True
except GovernanceError as e:
    # Base class. Catch infrastructure failures (gateway unreachable, invalid key).
    handle_infra_error(e)

Order except clauses from most specific to most general. AgentTerminated before ToolBlocked before GovernanceError.

Exception classes

Common attributes

All three exception classes expose the same attribute set for consistent error handling:

All attributes are populated. Accessing any attribute on any exception will not raise AttributeError.

Utility methods

pe.scan(text)

Pre-scan text for PII or prompt injection before sending to an LLM. Useful for catching risky input before it hits a tool.

result = pe.scan("Customer SSN is 123-45-6789")
# {
#   "patterns": ["SSN"],
#   "pii_detected": True,
#   "prompt_injection": False
# }

Returns an empty dict if the gateway is unreachable. Never raises.

pe.status()

Check gateway status and session activity.

result = pe.status()
# {
#   "status": "operational",
#   "active_sessions": 2
# }

Additional implementation fields may appear. Only status and active_sessions are guaranteed.

Returns an {"error": ...} dict on failure. Never raises.

Agent lifecycle methods

The SDK can suspend and reinstate its own agent. This is useful for self-quarantine when the application detects anomalous behavior.

pe.quarantine(reason)

Suspend all tool access for the agent. All subsequent calls are blocked at the gateway. Reversible with pe.reinstate().

pe.quarantine(reason="Anomalous behavior detected: 30 calls in 10 seconds")

Anchors AGENT_QUARANTINED event to the audit chain. Takes effect within one second.

pe.reinstate(reason)

Restore tool access for a quarantined agent. Has no effect on a killed agent.

pe.reinstate(reason="Investigation complete. Behavior normalized.")

Anchors AGENT_REINSTATED event to the audit chain.

pe.kill()

The kill switch is not available through the SDK. Kill is permanent and irreversible, so it is restricted to the Console. Calling pe.kill() raises GovernanceError with a message directing you to the Console at phronedge.com/brain.

The 7 checkpoints

Every governed tool call passes through 7 checkpoints in the gateway. The function body does not execute until all 7 pass.

The checkpoint that blocked the call is available as e.checkpoint on the exception (or result["checkpoint"] in soft-block mode).

Credential caching

The SDK caches the credential for 5 minutes after the first fetch. This means the first call in a session makes one HTTP request to /auth/credential, and subsequent calls reuse the cached credential until it expires.

To force a fresh credential fetch:

pe._credential = None
pe._credential_ts = 0

This is rarely needed. The credential auto-refreshes. Use this only when you know the credential has changed out-of-band (for example, immediately after a policy amendment from a different session).

Thread safety

One PhronEdge instance is safe to share across threads. The underlying requests.Session is thread-safe for read operations, and the credential cache is single-writer.

For async frameworks, the SDK uses synchronous HTTP calls via requests. For high-throughput async workloads, run the decorated function in a thread pool:

import asyncio
result = await asyncio.to_thread(my_governed_tool, "arg")

Versioning

Upgrade:

pip install --upgrade phronedge

Next steps

• Quickstart. 2-minute end-to-end
• CLI reference. All 14 commands
• REST API reference. For non-Python clients
• Framework guides. LangGraph, CrewAI, Google ADK, OpenAI Agents, LlamaIndex
• Multi-agent governance. Orchestrators, sub-agents, delegation
• Signing and verification. ECDSA signatures, independent verification