AI Agent Firewall

1 Quick Start Guide

2 Python SDK Integration

ZEQCY currently provides a local Python integration for agent requests. You can connect a local Python AI agent to the firewall to evaluate its tool execution requests. Note: The current v0.1.2 release operates strictly in simulation-only mode. Real tool execution is disabled by the firewall, and external AI APIs are not required.

1. Start ZEQCY: Download and run the ZEQCY Firewall locally.
2. Import: Include the zeqcy_agent.py connector in your Python project.
3. Initialize: Configure the connector with your agent's identity.
4. Health Check: Safely verify connectivity to the local firewall.
5. Evaluate: Submit a simulated agent action.
6. Read Decision: Inspect the firewall decision (ALLOWED, REVIEW_REQUIRED, BLOCKED, or ERROR).

from zeqcy_agent import ZEQCYFirewall

# 1. Initialize connector
firewall = ZEQCYFirewall(
    agent_id="my-agent",
    session_id="session-001"
)

# 2. Check connectivity
health = firewall.health()
if health.get("status") != "online":
    print("ZEQCY Firewall is unreachable!")

# 3. Submit an action
result = firewall.evaluate(
    tool="WEB_SEARCH",
    action="search",
    target="science news"
)

# 4. Inspect decision
if result.is_allowed():
    print("Action permitted (Simulated)")
elif result.requires_review():
    print("Action requires review.")
elif result.is_blocked():
    print("Action blocked!")
else:
    print("Safe failure or error.")

3 Framework-Neutral Agent Integration

You can use the framework-neutral adapter to consistently wrap the SDK for different agent implementations. This is an abstraction layer that allows your custom agents to interact seamlessly without duplicating integration logic. Note: This is an integration abstraction, NOT universal framework support. Real tool execution remains disabled.

1. Connect: Create/connect to the ZEQCY SDK.
2. Adapter: Create an agent adapter.
3. Submit: Submit an action through the adapter.
4. Receive: Receive the firewall decision safely.
5. Handle: Handle the decision appropriately. No tool is executed automatically.

from zeqcy_agent import ZEQCYFirewall, ZEQCYAgentAdapter

# 1. Connect SDK
firewall = ZEQCYFirewall(agent_id="my-agent", session_id="sess-1")

# 2. Create Adapter
agent_adapter = ZEQCYAgentAdapter(firewall)

# 3. Submit request securely
result = agent_adapter.request(
    tool="WEB_SEARCH",
    action="search",
    target="AI agent security"
)

# 4. Handle decision securely
if result.is_allowed():
    print("Safe to proceed (Simulated).")
else:
    print("Firewall blocked the action.")

4 Agent Request Interception

You can build a reusable interception workflow using the ZEQCY request interceptor. This allows agent actions to consistently pass through ZEQCY before any future execution layer. Note: Current ZEQCY integration is simulation-only and does not execute tools.

1. Action: Agent creates an action intent.
2. Intercept: Interceptor receives the action.
3. Evaluate: ZEQCY evaluates the action securely.
4. Decision: Firewall returns the authoritative decision.
5. Gate: Interceptor returns the decision, enabling the future execution layer to use it securely.

from zeqcy_agent import ZEQCYFirewall, ZEQCYAgentAdapter, ZEQCYRequestInterceptor

# 1. Setup
fw = ZEQCYFirewall(agent_id="agent-1", session_id="sess-1")
adapter = ZEQCYAgentAdapter(fw)
interceptor = ZEQCYRequestInterceptor(adapter)

# 2. Intercept Agent Action
result = interceptor.intercept(
    tool="WEB_SEARCH",
    action="search",
    target="science news"
)

# 3. Security Gating (Simulation-only)
if result.is_allowed():
    print("Proceed with future execution.")
else:
    print("Execution halted.")

5 Lifecycle Hooks

You can attach safe, observational callbacks (hooks) around the ZEQCY request interceptor. Hooks are invoked before interception, after evaluation, or on error. Note: Lifecycle hooks are observational integration points. They do not control ZEQCY security decisions and do not execute tools. Callbacks cannot modify internal state, and callback exceptions are caught safely.

# 1. Define safe observational hooks
def log_before(req_data):
    print(f"Agent intent: {req_data['action']} on {req_data['target']}")

def log_after(res_data):
    print(f"Firewall decision: {res_data['decision']}")

def log_error(err_data):
    print(f"Firewall error: {err_data['result']}")

# 2. Register hooks with the interceptor
interceptor.add_before_hook(log_before)
interceptor.add_after_hook(log_after)
interceptor.add_error_hook(log_error)

# 3. Intercept as usual
result = interceptor.intercept("WEB_SEARCH", "search", "science news")

6 Security Context

Security Context provides a structured, framework-neutral mechanism to attach safe observational metadata to agent requests. It is heavily bounded to basic types (strings, numbers, booleans) to protect sensitive data. Note: Security Context is metadata for tracing and integration only. It does not control ZEQCY security decisions and cannot alter firewall logic.

from zeqcy_agent import ZEQCYSecurityContext

# 1. Create safe context
ctx = ZEQCYSecurityContext({
    "workflow": "document_processing",
    "priority": 1,
    "is_prod": True
})

# 2. Pass context into interceptor (or adapter directly)
result = interceptor.intercept(
    tool="WEB_SEARCH",
    action="search",
    target="latest compliance news",
    context=ctx
)

# 3. Context propagates securely to hooks and the result details
print(result.details.get("context"))

2 Architecture & Simulation

The current release operates strictly in Simulation Mode. The system evaluates AI agent prompts, classifies the risk, and returns a security decision without executing any real-world actions.

• No Real Execution: The system does NOT run shell commands, delete real files, or access your network.
• Security Evaluation: It focuses purely on analyzing intent, matching security rules, and providing the correct decision boundary.
• Authoritative Backend: All decisions are made by the compiled local Python firewall engine, not the web frontend.

3 Understanding Decisions