Skip to main content
You have Apie connected. Now you need to decide how much instrumentation code to write. The right path depends on where your agent runs and how much control you need over guardrail metadata. When you finish this page, you’ll know which integration tier fits your setup and have a starting code snippet to copy.

​
The four tiers

TierWhen to useEffortGuard metadata
MCP proxyMCP hosts (Cursor, Claude Desktop)Config onlyInferred from tool names; override in proxy config
Framework pluginLangChain, OpenAI Agents, CrewAI~5 linesInferred inside runs; add explicit metadata for production
Request wrapperHTTP handlers, workers, CLI jobs1 wrapperRun context auto-propagates to plugins and MCP clients
Explicit instrumentationCustom agents, fine-grained control~10 lines per toolFull tool, action, resource metadata per call
Start at the lowest tier that fits your runtime. Add metadata as you move toward production Enforce mode.

​
Tier 1 — MCP proxy (config only)

If your agent uses MCP tools through Cursor or Claude Desktop, you don’t need to change agent code. Point the MCP host at the Apie proxy instead of the upstream server. 
npx apie mcp proxy --config apie.mcp.json
See MCP proxy for the full setup. Best for: Observing and guarding MCP tool calls without touching your agent.

​
Tier 2 — Framework plugin

Pass an Apie callback handler or run hooks to your framework. Tools inside a run are tracked automatically. 
import { ApieCallbackHandler } from "@apie-sh/sdk/integrations";
import apie from "./apie.config";

const handler = new ApieCallbackHandler(apie, {
  defaultEnvironment: "production",
});

await apie.withRun({ inputSummary: "Process request" }, async () => {
  // Pass handler to your LangChain agent callbacks
});
See Integrations for per-framework guides. Best for: LangGraph, OpenAI Agents, CrewAI, and similar frameworks where you control callbacks.

​
Tier 3 — Request wrapper

Wrap your HTTP handler or worker entrypoint. Apie creates a run for each request and propagates context to framework plugins and instrumented MCP clients. 
import apie from "./apie.config";

export const handleRequest = apie.wrap(
  async (req: Request) => agent.run(await req.json()),
  { inputSummary: (req) => req.url },
);
apie.wrap() is available in the JavaScript SDK. In Python, use run_context or with_run to establish run scope.
Best for: API routes, queue workers, and scheduled jobs where one request equals one run.

​
Tier 4 — Explicit instrumentation

Wrap each tool call with withTool / with_tool and provide metadata. This gives you the most control over guardrails and boundary maps. 
await apie.withRun({ inputSummary: "Process request" }, async (run) => {
  await apie.withTool(
    {
      runId: run.id,
      tool: { name: "search", riskLevel: "low" },
      action: { type: "read", name: "search" },
      resource: { type: "knowledge_base" },
    },
    async () => search("query"),
  );
});
Action and resource types are inferred from tool names when omitted — fine for Monitor mode. Add explicit metadata before enabling Enforce mode in production. See Instrument tool calls. Best for: Custom agents, production enforcement, and compliance-sensitive workloads.

​
Decision flowchart

​
Escalate to production

  1. Start in Monitor mode (default) — guardrails evaluate but never block
  2. Declare capabilities for expected tools
  3. Enable guardrail templates for your environment
  4. Switch to Enforce mode and add explicit action, resource, and riskLevel metadata

​
Next steps

Trace runs and sessions

Create runs for every agent invocation.

MCP proxy

Zero-code MCP instrumentation.