Policy, human approval and audit for any agent framework
Put one MAQPNA policy, human approval and the audit ledger in front of LangGraph, CrewAI, the OpenAI Agents SDK, the Claude Agent SDK or any MCP client, without changing how the framework works.
In this tutorial you write one policy, start a local MAQPNA, and put the same policy, the same human approval and the same audit ledger in front of whichever agent framework you use: LangGraph, CrewAI, the OpenAI Agents SDK, the Claude Agent SDK, or a plain Model Context Protocol (MCP) client. The framework keeps its own loop. Only the tools change: they come from the MAQPNA gateway, so every tool call is allowed, denied or held for a person before it runs.
flowchart LR
subgraph fw["Your agent (any framework)"]
LG["LangGraph"]
CR["CrewAI"]
OA["OpenAI Agents SDK"]
CA["Claude Agent SDK"]
MC["MCP client / HTTP"]
end
LG & CR & OA & CA & MC -->|"tool calls"| GW["MAQPNA gateway<br/>policy · approval · audit"]
GW -->|allowed| E["MCP server<br/>(mcp-echo)"]
GW -->|held| H["you, as approver<br/>maqpna approvals"]
GW --> L[("audit ledger<br/>.maqpna/audit.jsonl")]
| Time | About 15 minutes for one framework |
| Level | Beginner: you have an agent in one of these frameworks, or want to start one |
| You learn | One policy for every framework, the SDK adapters, approval modes, the raw MCP path, verifying the audit ledger |
What exists for each framework#
MAQPNA ships Python adapters for four frameworks and a plain MCP endpoint for everything else. Use this table to see what you get before you start:
| Framework | Adapter (Python SDK) | Ready-to-run template | How a held call looks to the framework |
|---|---|---|---|
| LangGraph | maqpna.integrations.langgraph (extra langgraph) |
examples-agents/langgraph/ |
interrupt(); resume with Command(resume=True) |
| CrewAI | maqpna.integrations.crewai (extra crewai) |
None | Tool output text, or the tool blocks (approvals="wait"). CrewAI has no interrupt mode. |
| OpenAI Agents SDK | maqpna.integrations.openai_agents (extra openai-agents); TypeScript in @kosa8/maqpna |
examples-agents/openai-agents/ |
Tool output text, a blocking tool, or a needs_approval interruption |
| Claude Agent SDK | maqpna.integrations.claude_agent_sdk (extra claude-agent-sdk) |
examples-agents/claude-agent-sdk/ |
PreToolUse hook answers ask; a retry resumes the approval |
| Any MCP client or HTTP | None needed: the gateway is an MCP endpoint at {gateway}/mcp/{server} |
None | JSON-RPC error -32002, or the request waits |
Every adapter is listed with its full API in Framework adapters. Whatever the framework shows, the person still decides in MAQPNA (the CLI, the console or MAQPNA Desk), and the gateway enforces that decision. A framework cannot approve its own calls.
Prerequisites#
- The
maqpnaCLI (see Install) and free ports 8080, 8081, 8090 and 8000. - Python 3.10 or later, for the adapter steps.
- For the templates only: a checkout of the MAQPNA source (from maqpna.com/github), with its path in
MAQPNA_SRC.
No API key is needed. maqpna dev up --stub-llm starts a scripted model behind the gateway.
Step 1: Write one policy for every framework#
The local gateway reads policies as bundle JSON. This policy has no agents list, so it applies to every agent in the local namespace dev, whichever framework it uses:
{
"policies": [
{
"name": "any-framework",
"namespace": "dev",
"defaultAction": "deny",
"rules": [
{
"name": "no-system-namespaces",
"servers": ["echo"],
"tools": ["*"],
"argMatch": {"namespace": "kube-*"},
"action": "deny",
"reason": "system namespaces are off-limits to agents"
},
{
"name": "read-only",
"servers": ["echo"],
"tools": ["echo", "get_time"],
"action": "allow"
},
{
"name": "deletes-need-a-human",
"servers": ["echo"],
"tools": ["delete_*"],
"action": "require_approval",
"reason": "destructive operation"
}
]
}
]
}
Save it as policies.json. Rules are checked in order and the first match decides; anything no rule matches is denied. The rule format is in Write policies.
Check it works#
maqpna policy test --policy policies.json --ns dev --agent any \
--server echo --tool delete_resource --args '{"namespace":"staging"}' --expect require_approval
It prints the decision as JSON and exits with status 0. See maqpna policy test.
Step 2: Script the model and start a local MAQPNA#
The stub model answers from a script, one step per assistant turn. This one makes the agent try a delete in kube-system, then one in staging, then finish:
# script.yaml
model: stub
steps:
- tool_calls:
- name: delete_resource
arguments: {id: "coredns", namespace: "kube-system"}
- tool_calls:
- name: delete_resource
arguments: {id: "cache-7", namespace: "staging"}
- content: "The kube-system delete was refused; the cache-7 delete went to a human."
The tool names match the LangGraph and OpenAI Agents SDK templates, which use the plain MCP tool name when the agent has one MCP server. Without a script, the stub's default asks for echo, then for a delete in kube-system, and never reaches the approval rule.
maqpna dev up --stub-llm --stub-llm-script script.yaml --policy policies.json
This starts the identity broker, the gateway, the test MCP server mcp-echo (tools echo, get_time and delete_resource, which only pretends to delete) and the stub model. Check with maqpna dev status. Every flag is in maqpna dev up.
Every command below runs under maqpna dev run. It mints a session token and sets MAQPNA_GATEWAY_URL, MAQPNA_TOKEN, MAQPNA_TOOL_ECHO_URL and the model variables, the same environment a sandbox gets in a cluster. MaqpnaClient.from_env() reads them.
Step 3: Connect your framework#
Pick your framework. Install the SDK with its extra first:
pip install "kosa8-maqpna[langgraph]" # or crewai, openai-agents, claude-agent-sdk
Use the adapter's ToolNode as the graph's tools node. A held call becomes interrupt():
from langgraph.types import Command
from maqpna import MaqpnaClient
from maqpna.integrations.langgraph import invoke_and_report, tool_node
client = MaqpnaClient.from_env()
tools = tool_node(client.tools("echo")) # the graph's "tools" node
graph = builder.compile(checkpointer=MemorySaver())
out = invoke_and_report(client, graph, {"messages": [("user", task)]}, config)
while "__interrupt__" in out: # a call is held for approval
print(out["__interrupt__"][0].value["approval_id"])
out = invoke_and_report(client, graph, Command(resume=True), config)
To run the full template instead, follow Build a governed LangGraph agent, or run it directly:
MAQPNA_WAIT_FOR_APPROVALS=true \
maqpna dev run -- python "$MAQPNA_SRC/examples-agents/langgraph/agent.py" "check the cluster and clean up"
Give the agent MAQPNA tools. Each one is a CrewAI BaseTool built from the MCP input schema:
from crewai import Agent
from maqpna import MaqpnaClient
from maqpna.integrations.crewai import as_tools
client = MaqpnaClient.from_env()
ops = Agent(role="operator", goal="…", backstory="…",
tools=as_tools(client.tools("echo"), approvals="wait"))
With approvals="wait" the tool blocks until a person decides. With the default "error", the model gets approval pending: id=… as tool output, and a retry of the same call resumes that approval. CrewAI has no interrupt mode, and there is no CrewAI template in the source: run your own script with maqpna dev run -- python crew.py.
Two ways in. Function tools map every gateway decision; native MCP lets the Agents SDK talk MCP to the gateway itself:
from agents import Agent
from maqpna import MaqpnaClient
from maqpna.integrations.openai_agents import function_tools, mcp_server
client = MaqpnaClient.from_env()
# 1. Function tools: approvals="error", "wait" or "interrupt"
agent = Agent(name="ops", tools=function_tools(client.tools("echo"), approvals="interrupt"))
# 2. Native MCP: approvals are synchronous on this path
async with mcp_server(client, "echo") as echo:
agent = Agent(name="ops", mcp_servers=[echo])
With "interrupt", the tool's needs_approval hook turns a held call into an Agents SDK interruption; after state.approve(...), the tool polls the MAQPNA approval and returns the result. The template uses "wait" when MAQPNA_WAIT_FOR_APPROVALS=true:
MAQPNA_WAIT_FOR_APPROVALS=true \
maqpna dev run -- python "$MAQPNA_SRC/examples-agents/openai-agents/agent.py" "check the cluster and clean up"
TypeScript has the same with openaiAgentsTools and openaiAgentsMcpServerOptions from @kosa8/maqpna (see TypeScript SDK).
Serve MAQPNA tools as an in-process MCP server, and let the hooks turn gateway decisions into Claude permission decisions:
from claude_agent_sdk import ClaudeAgentOptions
from maqpna import MaqpnaClient
from maqpna.integrations.claude_agent_sdk import MaqpnaPermissions, query_and_report, sdk_mcp_server
client = MaqpnaClient.from_env()
perms = MaqpnaPermissions()
servers = {"echo": sdk_mcp_server(client, "echo", permissions=perms)}
options = ClaudeAgentOptions(mcp_servers=servers, hooks=perms.hooks())
async for message in query_and_report(client, "check the cluster and clean up", options):
...
The PreToolUse hook answers deny for a call the gateway denied and ask for one with a pending approval. Approvals are asynchronous: a held call returns at once and a retry resumes it. To let Claude call the gateway over HTTP instead, use mcp_servers(client), which returns {"<server>": {"type": "http", "url", "headers"}}. The template runs in offline mode under the stub model (no Anthropic credentials needed) and in live mode with them. In offline mode, if its tool names do not match the script, make the held call with maqpna call from the "MCP client or HTTP" tab instead:
maqpna dev run -- python "$MAQPNA_SRC/examples-agents/claude-agent-sdk/agent.py" "check the cluster and clean up"
No adapter is needed. The gateway is an MCP endpoint: send JSON-RPC to {gateway}/mcp/{server} with the session token as a bearer token. Any MCP client that can call a streamable HTTP server with an Authorization header works the same way. With curl:
maqpna dev run -- sh -c 'curl -sS "$MAQPNA_TOOL_ECHO_URL" \
-H "Authorization: Bearer $MAQPNA_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "X-Maqpna-Async: 1" \
-d '"'"'{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"delete_resource","arguments":{"id":"cache-7","namespace":"staging"}}}'"'"''
With X-Maqpna-Async: 1 the gateway answers at once with error -32002 and the approval ID instead of waiting. After the call is approved, retry it with X-Maqpna-Approval-Id: <id>. Without the header, the request waits for the decision. The full contract is in Call tools over MCP and Handle decisions in code. The quickest check from a shell is maqpna call:
maqpna dev run -- maqpna call --server echo --tool delete_resource --arg id=cache-7 --arg namespace=staging
Check it works#
Whichever path you chose, a call to delete_resource in kube-system comes back denied by rule no-system-namespaces, and a call in staging is held. The framework shows that hold as described in the table above.
Step 4: Decide as a human#
In a second terminal, in the same folder, load the local admin token and list what is pending:
eval "$(maqpna dev env)"
maqpna approvals list
Approve it as someone other than the user the agent acts for. Approvers cannot approve calls made on their own behalf:
maqpna approvals approve apr_... --approver reviewer@localhost --note "cache-7 is a scratch cache"
Or deny it with maqpna approvals deny apr_... --approver reviewer@localhost --note "...": the agent then gets a tool error with reason approval_denied. You can also decide in the console or MAQPNA Desk. For calls that need two people, set approval: {minApprovers: 2} on the rule (four-eyes approval; it needs approvers with their own credentials, so it cannot be completed on a local MAQPNA). See Approvals, four-eyes and user approval.
Step 5: Read and verify the audit ledger#
Every decision above, from every framework, is in the same ledger:
maqpna dev timeline --last
maqpna audit verify .maqpna/audit.jsonl
The timeline lists the allowed, denied and held calls with the policy and rule that decided each one. audit verify recomputes the hash chain and prints OK when no record was changed, removed or reordered. See The audit ledger and maqpna audit verify.
Recap#
- One policy governs every framework, because the decision is made at the MAQPNA gateway, not in the framework.
- The adapters only translate the gateway's decisions into what each framework already understands:
interrupt()in LangGraph,needs_approvalin the OpenAI Agents SDK, an ask hook in the Claude Agent SDK, tool output in CrewAI. - A framework without an adapter uses the gateway as a plain MCP endpoint.
- The audit ledger records every decision the same way, whichever framework made the call.
Clean up#
maqpna dev down
Next steps#
- Deploy the same agent to a cluster with an
Agent, aToolPolicyand anAgentSession: Use a framework template. - Hold only risky calls, based on arguments: Support agent with DLP and approvals.
- Every approval option, from Slack to user approval on the person's own device: Human approvals.
Last updated