Securing CrewAI & LlamaIndex Workflows with X.509 Certs

TL;DR

• Kakunin's SDK wraps CrewAI Agents and LlamaIndex QueryEngineTools to enforce X.509 certificate verification on every tool call, not just at startup.
• Delegation chains use RFC 8693 token exchange: each hop from manager agent to sub-agent to tool call narrows scope — never widens it.
• Vector store queries get their own risk category, since a silently over-broad retrieval looks identical to normal traffic in a log line.
• Local debugging tip: most 'stuck sub-agent' issues are the gateway rejecting an unauthorized tool call, not a framework bug.
• Certificate verification adds low-double-digit milliseconds per tool call when connections are pooled — negligible against LLM inference time.

How do you add certificate-based security to a CrewAI or LlamaIndex agent?

Wrap the CrewAI Agent or LlamaIndex QueryEngineTool with Kakunin's SDK instead of instantiating it directly from the framework. The wrapper intercepts every tool call — not just agent startup — and verifies the agent's X.509 certificate against the mTLS gateway before the call executes. Delegation between agents uses RFC 8693 token exchange so each sub-agent inherits a scope that's a subset, never a superset, of its parent's.

Multi-Agent Orchestration Frameworks

Multi-agent frameworks like CrewAI and LlamaIndex allow developers to build complex autonomous systems where specialized agents collaborate — passing tasks, querying vector stores, and executing external tool calls sequentially.

However, as agent orchestration chains grow deeper, tracking accountability and enforcing authority boundaries becomes extremely difficult. If a sub-agent hallucinates an unauthorized API call, how does your infrastructure detect and block the action?

This tutorial demonstrates how to integrate Kakunin's TypeScript and Python SDKs into CrewAI and LlamaIndex workflows to enforce X.509 certificate verification on every tool call.

---

Securing Delegation Chains

In CrewAI, tasks are delegated between hierarchical agents. Kakunin tracks nested delegation chains using RFC 8693 token delegation claims, ensuring that sub-agents inherit the restricted scope of their parent agent.

For detailed SDK method signatures, explore our KYC Integration Documentation.

Wrapping a CrewAI Agent with the Kakunin Middleware

CrewAI agents execute tools through a callback interface that sits between the LLM's function-call decision and the actual Python function invocation. Kakunin's TypeScript and Python SDKs hook into exactly that seam. Instead of instantiating a bare CrewAI Agent, you construct it through a KakuninAgentWrapper (Python) or wrapAgent() (TypeScript), passing the agent's KMS-issued X.509 identity alongside the usual role, goal, and tool list. The wrapper does not change how you write CrewAI code — it intercepts the agent's execute_task and tool-invocation hooks and inserts a certificate verification step before any tool body runs.

Under the hood, the wrapper calls client.certificates.verify() against the mTLS API gateway on every tool call, not just once at agent startup. This matters because a CrewAI agent's certificate can be revoked mid-session if its behavioral risk score crosses the 0.85 auto-revocation threshold — a long-running Crew with multiple sequential tasks needs per-call verification, not a single handshake at boot. The gateway checks the certificate against the current CRL/OCSP state, which Kakunin guarantees reflects any revocation within 60 seconds of the triggering event, and returns an allow/deny decision alongside a risk score that the wrapper can log or act on.

Verifying Tool Calls Inside a Task

In practice, wrapping a Task means passing its callback through kakunin.certifyTool() (or the equivalent @certified_tool decorator in Python) rather than registering the raw function on the Agent. When CrewAI's planner decides to invoke, say, a send_email or query_database tool, the decorator intercepts the call, extracts the agent's certificate fingerprint from the active session context, and submits a verification request that includes the tool name, the argument payload's size and shape (not its full contents, to avoid leaking sensitive data into the audit trail), and the current delegation depth. Every verification attempt — allowed or blocked — writes a row to the WORM-backed audit_log via writeAuditLog(), so a compliance reviewer can reconstruct exactly which sub-agent tried to call which tool, at what risk score, and why it was permitted or stopped.

One detail worth calling out for CrewAI specifically: because Crews often run tasks in a hierarchical process where a manager agent assigns work to workers, the wrapper needs the manager's certificate context to be available when it constructs each worker's Task object. If you build Task objects with a bare agent reference instead of routing them through kakunin.assignTask(), the resulting sub-agent will not inherit a scoped certificate, and the gateway will reject its very first tool call rather than silently letting it run unauthenticated.

Instrumenting LlamaIndex Query Engine Tools

LlamaIndex workflows typically expose retrieval and querying capability as a QueryEngineTool, which an agent calls the same way it would call any other function tool. Kakunin's Python SDK provides a CertifiedQueryEngineTool wrapper that takes an existing query_engine instance and returns a drop-in replacement with the same .query() and .aquery() interface — the rest of your LlamaIndex pipeline, including retrievers, node postprocessors, and response synthesizers, is untouched.

The wrapper's verification step runs asynchronously alongside the retrieval call rather than strictly before it, using QStash to fan out the audit_log write so the query's response latency isn't blocked on the WORM insert completing. The certificate check itself — confirming the calling agent's cert is valid and scoped to invoke this particular query engine — does block the query, since an unauthorized query should never reach the vector store at all. This split is deliberate: verification is on the latency-critical path, audit logging is not.

Treating Vector Store Queries as a Distinct Risk Category

Vector store retrieval deserves its own risk category rather than being scored like a generic tool call, because the failure mode is different. A miscalibrated API call typically fails loudly; a vector store query that quietly returns documents outside an agent's intended scope fails silently and looks like normal behavior in a log line — which is exactly the profile of a data exfiltration attempt, whether the retrieval scope was hallucinated by the LLM or deliberately manipulated through a prompt injection embedded in retrieved content. Kakunin's behavioral risk engine weights query-tool events using signals specific to retrieval: the number of documents returned per call, whether the query touches a namespace or collection outside the agent's declared scope, and whether the same sub-agent issues an unusually high volume of broad queries in a short window compared to its historical baseline.

These signals feed into the same 0.00–1.00 real-time risk score used for every other tool call, so a sequence of over-broad vector queries can push a sub-agent's score past the 0.85 threshold and trigger auto-revocation within the standard 60-second SLA — even if no single query looked obviously wrong in isolation. In practice, this means a LlamaIndex retrieval agent that starts querying collections it has never touched before, or that returns node counts far above its rolling average, gets flagged and can be cut off before it assembles a response that leaks cross-tenant or restricted content back to the orchestrating agent.

Scope Narrowing Across a Three-Level Delegation Chain

A typical CrewAI hierarchy — manager agent delegates to a specialist sub-agent, which invokes a single tool — maps directly onto RFC 8693 token delegation claims. The manager agent's certificate carries the full scope it was provisioned with: the complete tool list, the full set of accessible vector collections, whatever the tenant configured. When the manager delegates a task to a sub-agent, Kakunin's SDK performs a token exchange that mints a new delegation claim naming the manager as the acting party and the sub-agent as the delegate, with a scope that is the intersection of the manager's scope and whatever the task explicitly requires — never a superset.

The third hop, sub-agent to tool, narrows again. When the sub-agent actually invokes a tool, the certificate presented to the mTLS gateway carries a delegation chain three claims deep: tenant root authority, manager agent, sub-agent, each with monotonically decreasing scope. A researcher sub-agent spawned to answer one question might inherit read-only access to two vector collections from a manager that itself has read-write access to five — and when that sub-agent calls its single query tool, the certificate it presents is scoped to exactly that one tool invocation, not the sub-agent's broader read-only grant.

This matters operationally because scope narrowing is enforced at verification time, not just declared in configuration. If a sub-agent's LLM decides — correctly or as a hallucination — to call a tool outside its delegated scope, the gateway rejects the request before it reaches your function code, regardless of what the CrewAI or LlamaIndex framework itself would have permitted. The framework has no concept of delegation scope; Kakunin's certificate chain is what actually enforces the boundary.

• Level 1 — parent/manager agent: full tenant-provisioned scope
• Level 2 — sub-agent: scope intersected with the specific task assignment
• Level 3 — tool invocation: scope narrowed to the single action being attempted

Debugging a Blocked or Revoked Sub-Agent in Local Development

The most common support question from developers integrating CrewAI or LlamaIndex with Kakunin is some version of "my sub-agent stopped responding partway through a run." In nearly every case this is the gateway rejecting a tool call, not a framework bug — CrewAI and LlamaIndex both swallow the resulting exception into a generic tool-error message unless you've configured verbose logging on the wrapper itself.

Start by checking the certificate status and current risk score for the specific agent identity, not the Crew or workflow as a whole — each sub-agent has its own certificate, so a manager agent staying healthy while a worker gets revoked is expected behavior, not a bug. The SDK's dev-mode client exposes a local inspect() call that returns the last verification decision, the risk score at the time of the block, and the specific delegation claim that failed scope validation, without needing to query the dashboard. The three causes that account for almost all local-dev blocks are: an expired short-lived delegation certificate (these are intentionally scoped to the task's expected duration, so a debugger paused mid-run can outlast it), a scope mismatch where the sub-agent's tool call falls outside what its RFC 8693 claim authorized, and a risk score that crossed 0.85 because of repeated retries against the same tool — which local development triggers more often than production, since developers re-run failing steps far more frequently than a tuned production agent would.

For local iteration, it's worth issuing agents short-lived sandbox certificates through the dev CLI rather than reusing production identities — revocations in sandbox mode don't propagate to the production CRL, so you can safely push an agent past the risk threshold to observe the block behavior without affecting real traffic.

Production Deployment Considerations

A CrewAI Crew or LlamaIndex agentic workflow that fans out across many tools and sub-agents can generate a high volume of certificate verification calls per run, and naively opening a new mTLS connection to the gateway on every tool call adds unnecessary handshake overhead at scale. Both SDKs default to a pooled connection to the gateway, reused across an agent's lifetime rather than per tool call — configure the pool size to match your expected concurrency (number of simultaneously running sub-agents per process), not the number of tools, since tool calls from the same agent share one verified session.

Rate limiting also needs to be considered at the infrastructure layer, not just the certificate layer: Upstash Redis enforces per-tenant request limits ahead of any database write, which means a runaway CrewAI loop that retries a failing tool aggressively will hit rate limits before it hits the risk-scoring threshold. Size your Redis limits with agentic retry patterns in mind — LLM-driven agents retry differently than deterministic services, often in short bursts rather than steady intervals.

Latency Budget for Certificate Verification per Tool Call

Every tool call in a certified workflow now carries the added cost of a gateway round trip. In practice this adds low-double-digit milliseconds per call when the connection is pooled and the certificate's validity has already been cached locally with a short TTL — the SDK caches a positive verification result for a few seconds so a sub-agent making several rapid calls to the same tool doesn't re-verify identically on every invocation, while still re-checking often enough to catch a mid-run revocation well within the 60-second SLA.

For a three-level delegation chain executing a dozen tool calls across a CrewAI hierarchy, this typically adds a few hundred milliseconds of cumulative latency to the full run — negligible against LLM inference time, but worth budgeting explicitly if your workflow has a hard end-to-end SLA. The trade-off is not optional: skipping verification to save latency reintroduces exactly the accountability gap this integration exists to close, so the right lever is caching and connection reuse, not disabling checks on high-frequency tool paths.

For SDK installation steps and the full method signatures referenced above, see the KYC Integration Documentation at /docs/sdk.

Handling Framework Upgrades Without Breaking Certificate Bindings

CrewAI and LlamaIndex both ship frequent releases, and a version bump can change internal callback signatures that Kakunin's wrapper depends on to intercept tool calls. The SDK pins against tested minor-version ranges for both frameworks and fails loudly at import time — rather than silently degrading to unverified tool execution — if it detects a framework version outside that tested range. This fail-closed behavior is a deliberate tradeoff: a broken integration that blocks agent startup is recoverable by pinning dependencies; a broken integration that silently stops verifying tool calls while the agent keeps running is a much harder incident to detect, since nothing in the application's normal error handling would surface it.

When upgrading CrewAI or LlamaIndex in a certified workflow, the recommended sequence is to bump the framework version in a staging environment first, confirm the Kakunin SDK still reports a supported version match, and run a full pass through the sandbox certificate flow described above before promoting to production. Framework release notes rarely call out changes to internal hooks explicitly, which is why relying on the SDK's own compatibility check — rather than assuming an upgrade is safe because the agent's business logic didn't change — is the safer default for certified deployments.