Arden documentation

Arden sits between your AI agent and its tools. Every tool call is evaluated against policies you configure in the dashboard before the function runs. The policy engine returns one of three decisions:

Every call is logged regardless of outcome — you get a full audit trail from day one, even for tools with no policy configured.

Install the SDK:

pip install ardenpy

Get your API key from app.arden.sh. Keys starting with arden_test_ hit the test environment; arden_live_ keys hit production.

Configure once at startup:

import ardenpy as arden

arden.configure(api_key="arden_live_...")
# For LangChain, CrewAI, and OpenAI Agents SDK — that's it.
# Every tool call in this process is now intercepted, enforced, and logged.

For custom agents without a framework, wrap functions explicitly with guard_tool():

safe_refund = arden.guard_tool("issue_refund", issue_refund)
result = safe_refund(150.0, customer_id="cus_abc")
# → allowed · blocked · or held for human approval

Every tool call follows the same sequence:

1. 1The agent calls a tool (e.g. issue_refund).
2. 2Arden intercepts the call and sends the tool name and all arguments to the policy engine.
3. 3The engine looks up the policy for this agent and tool. If no policy exists, the call is allowed and logged.
4. 4For requires_approval, the call pauses. A human approves or denies on the dashboard. For allow, the function runs immediately. For block, PolicyDeniedError is raised.

The integration path depends on which framework your agent uses.

pip install ardenpy

import ardenpy as arden

arden.configure(api_key="arden_live_...")
# Done. No protect_tools(), no guard_tool(), no imports.

# LangChain — use tools exactly as before
from langchain.tools import Tool
tools = [Tool(name="issue_refund", func=issue_refund, description="...")]
agent = create_react_agent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools)
executor.invoke({"input": user_message})
# Every tool the agent calls is policy-checked automatically

# CrewAI — define BaseTool subclasses as usual
from crewai.tools import BaseTool

class RefundTool(BaseTool):
    name: str = "issue_refund"
    description: str = "Issue a refund to a customer"
    def _run(self, amount: float, customer_id: str) -> str:
        return f"Refund of {amount} issued"

agent = Agent(role="Support", tools=[RefundTool()], ...)
# Every _run() call is intercepted — no changes to tool classes needed

pip install ardenpy

import ardenpy as arden
from agents import Agent, function_tool, Runner

arden.configure(api_key="arden_live_...")

@function_tool
def issue_refund(amount: float, order_id: str) -> str:
    return f"Refund of {amount} issued for {"{order_id}"}"

# No wrapping needed — configure() already intercepted this tool
agent = Agent(name="SupportBot", tools=[issue_refund])
result = await Runner.run(agent, "Refund order FF-4210 for $500")

# OpenAI Chat Completions loop
from ardenpy.integrations.openai import ArdenToolExecutor

executor = ArdenToolExecutor()
executor.register("issue_refund", issue_refund)
executor.register("send_email", send_email)

# In your tool-call loop:
result = executor.run(tc.function.name, json.loads(tc.function.arguments))

import ardenpy as arden

arden.configure(api_key="arden_live_...")

safe_refund = arden.guard_tool("issue_refund", issue_refund)
safe_email  = arden.guard_tool("send_email",   send_email)

result = safe_refund(150.0, customer_id="cus_abc")

When a policy returns requires_approval, the SDK's behavior is controlled by the approval_mode you set on guard_tool() (or on protect_tools() if using explicit wrapping).

safe_refund = arden.guard_tool("issue_refund", issue_refund)
# approval_mode="wait" is the default

safe_refund = arden.guard_tool(
    "issue_refund", issue_refund,
    approval_mode="async",
    on_approval=handle_approved,
    on_denial=handle_denied,
)

result = safe_refund(150.0, customer_id="cus_abc")
# Returns PendingApproval immediately — never blocks
# on_approval / on_denial called from a background thread when a human acts

safe_refund = arden.guard_tool(
    "issue_refund", issue_refund,
    approval_mode="webhook",
    on_approval=handle_approved,
    on_denial=handle_denied,
)

result = safe_refund(150.0, customer_id="cus_abc")
# Returns PendingApproval immediately
# Arden backend POSTs to your webhook URL when a human decides

Every tool call — regardless of policy outcome — is written to your agent's action log. This happens automatically once you call configure(). No additional setup required.

View the action log for any agent at app.arden.sh. You can also check a specific action's status via the API:

curl 'https://api.arden.sh/status/<action_id>' \
  -H 'X-API-Key: arden_live_...'

Arden automatically tracks token consumption and estimated cost for every LLM call. For LangChain, CrewAI, and the OpenAI Agents SDK, configure() patches the framework at startup — no extra setup needed. Usage is sent in a background thread and adds no latency to your agent.

For custom agent loops, call log_token_usage() manually after each LLM response:

import ardenpy as arden

arden.configure(api_key="arden_live_...")

response = openai_client.chat.completions.create(
    model="gpt-4o",
    messages=messages,
)
arden.log_token_usage(
    model="gpt-4o",
    prompt_tokens=response.usage.prompt_tokens,
    completion_tokens=response.usage.completion_tokens,
)

ardenpy.log_token_usage(model, prompt_tokens, completion_tokens, session_id=None)

The dashboard shows cost broken down by model, day, and session — all scoped per agent. View it at app.arden.sh under the Usage tab for each agent.

Attach a session ID to a conversation or workflow run so every tool call from that session is grouped together in the action log. Use this to replay exactly what an agent did in a specific conversation — useful for debugging, auditing, and customer support.

Call arden.set_session() once at the start of each request or conversation turn. All subsequent policy-check calls in that async task or thread automatically carry the session ID.

import ardenpy as arden
import uuid

arden.configure(api_key="arden_live_...")

# FastAPI example — set once per request
@app.post("/chat")
async def chat(request: Request):
    body = await request.json()

    # Use an ID your app already tracks, or generate one
    session_id = body.get("session_id") or str(uuid.uuid4())
    arden.set_session(session_id)

    reply = await run_agent(messages)
    return JSONResponse({"reply": reply, "session_id": session_id})

The session ID is stored in a ContextVar, so it is scoped to the current async task. Concurrent requests never share a session ID, even without any extra locking.

Session ID shows up as a top-level field on every action record in the log:

ardenpy.set_session(session_id: str) -> None
ardenpy.get_session() -> str | None
ardenpy.clear_session() -> None

When using approval_mode="webhook", Arden POSTs a signed payload to your endpoint when a human approves or denies. Configure your webhook URL in the dashboard under agent settings.

Payloads are signed with HMAC-SHA256. Verify the signature before processing:

# FastAPI
from fastapi import FastAPI, Request
import ardenpy as arden

app = FastAPI()

@app.post("/arden/webhook")
async def webhook(request: Request):
    body = await request.body()
    arden.handle_webhook(
        body=body,
        headers=dict(request.headers),
    )
    # event_type is "action_approved" or "action_denied"
    # callbacks registered via guard_tool(on_approval=...) are called automatically
    return {"ok": True}

# Flask
from flask import Flask, request
import ardenpy as arden

app = Flask(__name__)

@app.post("/arden/webhook")
def webhook():
    arden.handle_webhook(
        body=request.get_data(),
        headers=dict(request.headers),
    )
    return {"ok": True}

import ardenpy as arden

try:
    result = safe_refund(150.0, customer_id="cus_abc")

except arden.PolicyDeniedError:
    # Blocked by policy, or denied by a human (wait mode)
    return {"ok": False, "reason": "not_allowed"}

except arden.ApprovalTimeoutError as e:
    # Nobody approved within max_poll_time
    return {"ok": False, "reason": "timeout", "action_id": e.action_id}

except arden.ArdenError as e:
    # API error, configuration error, etc.
    logger.error("Arden error: %s", e)
    return {"ok": False, "reason": "policy_check_failed"}

For async and webhook modes, only PolicyDeniedError (immediate block) and ArdenError can be raised at call time. ApprovalTimeoutError only applies to wait mode.

Arden has two isolated environments — test and live. Each has its own API keys, agents, policies, and action log.

The environment is auto-detected from the API key prefix. Use an environment variable to switch without code changes:

import os, ardenpy as arden

arden.configure(api_key=os.environ["ARDEN_API_KEY"])
# ARDEN_API_KEY=arden_test_... → test environment
# ARDEN_API_KEY=arden_live_... → live environment

All exceptions inherit from ArdenError.

class ArdenError(Exception)

class PolicyDeniedError(ArdenError):
    tool_name: str

class ApprovalTimeoutError(ArdenError):
    action_id: str
    timeout: float

class ConfigurationError(ArdenError)