Build Your Own Adapter
Learn how MACAW adapters work and how to integrate any AI framework with MACAW security.
The MACAW Model
MACAW has a simple abstract model: everything maps to an Agent. An Agent (MACAWClient) registers tools and prompts, then routes invocations through the MACAW control plane.
Your Framework
OpenAI / Anthropic
LangChain / CrewAI
Custom SDK
MACAWClient
register_tool()
invoke_tool()
log_event()
MACAW Control Plane
Cryptographic Signing
MAPL Policy Enforcement
Attested Audit Logs
Every adapter wraps a MACAWClient. Framework operations map to register_tool() + invoke_tool().
Invocation Flow
When you call invoke_tool(), MACAW handles the entire security lifecycle:
invoke_tool()
Agent lookup
Crypto sig
Enterprise rules
Handler runs
Irrefutable
Back to app
What MACAW Handles For You
- Cryptographic signing of all invocations (authenticity verified before execution)
- MAPL policy enforcement (requests allowed, denied, or modified based on enterprise rules)
- Prompt authentication (content filtering and lineage tracking for user content)
- Attested audit logs (irrefutable compliance records with cryptographic attestation)
- Identity verification via PKI (agent identities verified across the mesh)
Core Interfaces
1. Create the Agent
from macaw_client import MACAWClient
client = MACAWClient(
app_name="my-framework-adapter",
intent_policy={...} # Optional: MAPL format
)
client.register() # Join the MACAW meshEvery adapter creates a MACAWClient. This is your agent's identity in the MACAW mesh.
2. Register Tools
# Register operations as tools
client.register_tool(
name="generate", # Tool name (used in MAPL policies)
handler=self._generate, # Function to execute
prompts=["messages"] # Params needing content filtering
)
client.register_tool(
name="embed",
handler=self._embed,
prompts=["text"]
)Map your framework's operations to tools. The prompts parameter identifies which parameters contain user content for authenticated prompt handling.
3. Invoke Tools
# Route operations through MACAW
result = client.invoke_tool(
tool_name="generate",
parameters={
"model": "gpt-4",
"messages": [{"role": "user", "content": "Hello"}]
}
)
# MACAW handles: signing, policy check, execution, audit logAll the magic happens here. MACAW signs the request, checks policies, executes the handler, and logs everything.
4. Custom Logging (Optional)
# Add custom events for observability
client.log_event(
event_type="framework_specific",
source=client.agent_id,
action="custom_operation",
target="resource",
outcome="success",
signed=True # For compliance
)Add custom events to the audit trail for framework-specific telemetry and compliance.
Complete Example
"""Secure wrapper for any LLM framework."""
from macaw_client import MACAWClient
class SecureMyFramework:
def __init__(self, api_key: str, app_name: str = "secure-myframework",
intent_policy: dict = None):
# 1. Initialize underlying client
self._client = myframework.Client(api_key=api_key)
# 2. Create MACAW agent
self.macaw = MACAWClient(
app_name=app_name,
intent_policy=intent_policy
)
self.macaw.register()
# 3. Register framework operations as tools
self.macaw.register_tool("generate", self._generate, prompts=["messages"])
self.macaw.register_tool("embed", self._embed, prompts=["text"])
def _generate(self, params: dict):
"""Handler runs inside MACAW PEP - already protected."""
return self._client.chat(**params)
def _embed(self, params: dict):
return self._client.embed(**params)
# Public API - mirrors original framework
def chat(self, messages: list, **kwargs):
return self.macaw.invoke_tool("generate", {"messages": messages, **kwargs})
def embed(self, text: str, **kwargs):
return self.macaw.invoke_tool("embed", {"text": text, **kwargs})
# Usage - identical to original API
client = SecureMyFramework(
api_key="...",
intent_policy={"purpose": "customer support"}
)
response = client.chat([{"role": "user", "content": "Hello"}])What You Get Automatically
MAPL Tool Names
Tools are addressable in MAPL policies using the pattern tool:<app_name>/<tool_name>:
{
"policy_id": "team:analytics",
"resources": [
"tool:secure-myframework/generate", // Allow generate
"tool:secure-myframework/embed" // Allow embed
],
"denied_resources": [
"tool:secure-myframework/admin_*" // Block admin operations
],
"constraints": {
"parameters": {
"tool:secure-myframework/generate": {
"model": {
"allowed_values": ["gpt-4", "gpt-3.5-turbo"]
}
}
}
}
}