API Reference/MACAWClient

MACAWClient

The core SDK for the MACAW Trust Layer. Provides cryptographic identity, policy enforcement, and audit logging for AI agents and applications.

Installation

Download from the MACAW Console. Select your platform and Python version. The download includes your workspace API key.

bash

unzip macaw-client-*.zip
pip install ./macaw-client-*/*.whl

Quick Start

Create a client, register with the Control Plane, invoke a tool, then clean up.

1Create client with app identity

2Register to join the mesh

3Invoke tools

4Unregister when done

python

from macaw_client import MACAWClient

client = MACAWClient(app_name="my-agent")
client.register()

result = client.invoke_tool("database", {
    "query": "SELECT * FROM sales"
})

client.unregister()

Constructor

Create a client instance. Not connected until register() is called.

python

MACAWClient(
    app_name: str,                    # Required
    app_version: str = "1.0.0",
    agent_type: str = "agent",        # "agent" | "user" | "service"
    user_name: str = None,
    iam_token: str = None,            # Required if agent_type="user"
    provider: str = None,
    service_account: str = None,
    intent_policy: dict = None,
    tools: dict = None
)

Parameter	Type	Description
`app_name`required	str	Unique application identifier.
`app_version`	str	Version string. Default: "1.0.0"
`agent_type`	str	"agent" (autonomous), "user" (human-backed), or "service".
`user_name`	str	Human identifier. Example: "alice@sales-bot"
`iam_token`	str	JWT from enterprise IDP.
`provider`	str	IDP hint. Example: "okta", "keycloak"
`service_account`	str	Service account name.
`intent_policy`	dict	MAPL policy for permitted operations.
`tools`	dict	Tools this agent provides.

When agent_type="user", iam_token is required and service_account must not be set.

Methods

Registration with Control Plane

register()→bool

Creates cryptographic identity and joins the mesh. Embedded tools are registered with the Agent Registry.

unregister()→None

Clean up and leave the mesh.

Tool Operations

invoke_tool(tool_name, parameters, target_agent=None, stream=False)→dict | Iterator

Executes a signed, policy-enforced tool call.

register_tool(name, handler, prompts=None, attestation_config=None)→None

Registers a tool handler. Use prompts for content filtering.

Agent Discovery

list_agents(agent_type=None)→List[dict]

Lists registered agents. Filter by "user", "service", "tool", "app".

get_agent_info(agent_id)→dict | None

Returns agent details: tools, metadata, intent_policy.

External Attestations

list_attestations(status=None)→List[dict]

List attestations visible to this agent. Filter by status: "pending", "approved", "denied", "expired".

approve_attestation(attestation, reason=None)→bool

Approve a pending external attestation. Caller must match approval_criteria. Cryptographically signed.

deny_attestation(attestation, reason=None)→bool

Deny a pending external attestation. Caller must match approval_criteria. Requestor receives denial with reason.

App Context Vault

context_set(key: str, value: Any)→None

Stores value in context vault. Associated with authenticated principal. Audit-logged.

context_get(key: str)→Any

Retrieves value from context vault. Returns None if not found. Audit-logged.

Authenticated Prompts

create_authenticated_prompt(prompt_text, metadata=None)→AuthenticatedPrompt

Creates signed prompt. ROOT if none active, else DERIVED.

switch_prompt(prompt)→AuthenticatedPrompt | None

Switches context. Pass None, prompt_id, or AuthenticatedPrompt.

get_current_prompt()→AuthenticatedPrompt | None

Returns the active prompt.

Custom Logging

log_event(event_type, source, action, target, outcome, signed=False)→bool

Writes to audit log. Use signed=True for compliance events.

Examples

User Identity with Enterprise IDP

JWT claims (roles, groups) are used for policy resolution.

python

from macaw_client import MACAWClient
from macaw_client import RemoteIdentityProvider

idp = RemoteIdentityProvider()
result = idp.login("alice@company.com", password)

client = MACAWClient(
    app_name="sales-assistant",
    agent_type="user",
    iam_token=result["access_token"]
)
client.register()

result = client.invoke_tool("crm", {
    "customer_id": "12345"
})

Prompt Lineage

Derived prompts inherit and narrow the parent's scope.

python

client = MACAWClient(app_name="analyst")
client.register()

root = client.create_authenticated_prompt(
    "Analyze Q4 financials",
    metadata={"source": "cfo"}
)

# Auto-derives from root
refined = client.create_authenticated_prompt(
    "Focus on APAC expenses"
)
# refined.parent_id == root.prompt_id

Multi-Session Context

Manage separate prompt trees per user session.

python

# Session 1: Alice
alice = client.create_authenticated_prompt(
    "Show budget",
    metadata={"user": "alice"}
)

# Switch to Session 2: Bob
client.switch_prompt(None)
bob = client.create_authenticated_prompt(
    "List tickets",
    metadata={"user": "bob"}
)

# Return to Alice
client.switch_prompt(alice.prompt_id)

MACAWClient

Installation

Quick Start

Constructor

Methods

Registration with Control Plane

Tool Operations

Agent Discovery

External Attestations

App Context Vault

Authenticated Prompts

Custom Logging

Examples

User Identity with Enterprise IDP

Prompt Lineage

Multi-Session Context

Related

RemoteIdentityProvider

MAPL Structure

Adapters

Architecture