Skip to main content

Framework Integrations

Cordum sits between an agent framework and the tools the agent can invoke. The adapters turn tools advertised by cordum-mcp-bridge into framework-native tools; only calls made through those generated tools are governed by Cordum.

Supported frameworks​

FrameworkAdapterStatusTutorial
LangChaincordum-adapters[langchain]ShippedLangChain guard
LangGraphcordum-adapters[langchain] + graph wiringShippedLangGraph
CrewAIcordum-adapters[crewai]ShippedQuickstart · Safety gates
AutoGen / AG2cordum-adapters[autogen]ShippedQuickstart · Multi-agent tool partitioning
OpenAI Agents SDKcordum-adapters[openai-agents]ShippedQuickstart
LlamaIndex—Planned—
Temporal—Planned—

Install an adapter​

Packaged adapters are available on PyPI.

pip install cordum-adapters
pip install "cordum-adapters[langchain]"  # choose the extra you need

For unreleased adapter work, use an editable checkout instead:

git clone https://github.com/cordum-io/cordum-packs.git
pip install -e "./cordum-packs/integrations/agent-adapters[langchain]"

The Python package does not install the Go bridge or its Cordum pack. Build the two local binaries first:

mkdir -p "$HOME/.local/bin"

(cd cordum && go build -o "$HOME/.local/bin/cordumctl" ./cmd/cordumctl)
(cd cordum-packs/packs/mcp-bridge && \
  go build -o "$HOME/.local/bin/cordum-mcp-bridge" ./cmd/cordum-mcp-bridge)

export PATH="$HOME/.local/bin:$PATH"

A successful Python package install alone is not a runnable bridge.

Local Compose uses TLS​

From the parent workspace root, enter the Cordum core checkout and use the canonical bootstrap. Unlike the bare Compose target, this script creates .env, generates credentials and local TLS certificates, starts the stack, and waits for health:

cd cordum
./tools/scripts/quickstart.sh
set -a; source .env; set +a

The quickstart provisions the default Compose stack in TLS-only mode: the gateway is HTTPS, NATS uses TLS, and Redis uses TLS. The generated CA is ./certs/ca/ca.crt; framework clients and the bridge process must trust this CA rather than disabling certificate verification.

For a bridge launched on the host, export the secure endpoints and certificate material from that same checkout:

export CORDUM_GATEWAY_URL=https://localhost:8081
export CORDUM_GATEWAY="$CORDUM_GATEWAY_URL"  # cordumctl uses this name
export CORDUM_NATS_URL=tls://localhost:4222
export CORDUM_REDIS_URL="rediss://:${REDIS_PASSWORD}@localhost:6379"
export CORDUM_TLS_CA="$PWD/certs/ca/ca.crt"
export SSL_CERT_FILE="$CORDUM_TLS_CA"        # Go HTTPS trust on Unix-like hosts
export NATS_TLS_CA="$CORDUM_TLS_CA"
export NATS_TLS_CERT="$PWD/certs/client/tls.crt"
export NATS_TLS_KEY="$PWD/certs/client/tls.key"
export NATS_TLS_SERVER_NAME=localhost
export REDIS_TLS_CA="$CORDUM_TLS_CA"
export REDIS_TLS_SERVER_NAME=localhost

On Windows, import certs/ca/ca.crt into the current user's trusted root store for the bridge's HTTPS client. Keep CORDUM_TLS_CA set for the NATS and Redis SDK configuration. Do not replace these values with plaintext local URLs.

Now install the pack so job.mcp-bridge.tool, its pool, timeouts, and approval policy exist. This command requires the running gateway and the TLS/API-key environment above:

cordumctl pack install ../cordum-packs/packs/mcp-bridge/pack

Common wiring​

Pass the verified environment through to the stdio bridge; do not hard-code a second set of transport values in Python:

import os
from cordum_agent_adapters.mcp_client import McpStdioClient

client = McpStdioClient(
    command=["cordum-mcp-bridge"],
    env=os.environ.copy(),
)

Always discover tools from the running bridge:

tool_defs = client.list_tools()
print([tool["name"] for tool in tool_defs])

The current bridge pack advertises workflow run/rerun/cancel, job approve/reject/remediate/cancel, DLQ retry, and the adapter-facing audit tool. Treat tools/list as the runtime contract; do not invent convenience names in tutorial code.

Approval and hard-deny behavior​

The pack bridge submits each tool call as a Cordum job and polls that job synchronously. An approval decision leaves the job nonterminal, so the original tool call blocks while it waits for a human. The default CORDUM_MCP_CALL_TIMEOUT is 30s; use a larger bounded value for an interactive approval exercise and resolve the job from the dashboard in another window:

export CORDUM_MCP_CALL_TIMEOUT=5m

If approval arrives before the timeout, the original call continues; there is no approval-reference retry in this bridge. If the wait expires, or policy hard-denies the job, the bridge returns an MCP result with isError: true. McpStdioClient raises McpToolError, and each framework adapter converts that tool error into the framework's tool-result/error path.

Neither path is proof that an ungoverned framework call was intercepted. The agent must use the adapter-generated tools.

Optional conversation audit​

CordumConversationLogger is opt-in and best-effort. It submits turns only when the bridge advertises cordum.audit.log_turn; an unavailable audit tool does not abort the agent run.

from cordum_agent_adapters.audit import CordumConversationLogger

logger = CordumConversationLogger(client)

Tutorials​

See also​