Agents

An Agent in TraceMem is an AI system that makes decisions through TraceMem's governed execution boundary.

Key Principle: Agents can request actions, but they never authorize them. TraceMem enforces governance, records evidence, and creates audit trails.

What Agents Are

An Agent is:

An AI system that makes decisions affecting business systems
A client that interacts with TraceMem via Agent MCP (or future SDKs)
An initiator of Decision Envelopes
A requester of data access, policy evaluations, and approvals
An executor of actions within governed boundaries

It answers:

Who is making this decision, and how are they interacting with TraceMem to ensure it's governed and auditable?

What Agents Are Not

An Agent is not:

A workflow engine
A policy evaluator
An approval authority
A data store
A replacement for business logic

Agents bring their own intelligence and decision-making. TraceMem provides the execution boundary and governance layer, not the decision logic itself.

Agent Responsibilities

Agents are responsible for:

Creating Decision Envelopes - Opening decisions with clear intent and automation mode
Requesting Data Access - Reading data through Data Products with explicit purposes
Evaluating Policies - Checking if actions are allowed before proceeding
Requesting Approvals - Escalating to humans when policies require exceptions
Executing Actions - Writing data through Data Products after governance checks
Closing Decisions - Committing or rolling back decisions explicitly
Handling Errors - Managing failures and ensuring decisions are always closed

Agents are not responsible for:

Enforcing policies (TraceMem does this)
Authorizing actions (TraceMem does this)
Storing audit trails (TraceMem does this)
Managing approvals (TraceMem orchestrates this)

How Agents Interact with TraceMem

Current: Agent MCP (Model Context Protocol)

Agents currently interact with TraceMem through Agent MCP, a JSON-RPC 2.0 server that provides standardized tools for all agent operations.

Protocol:

JSON-RPC 2.0 over HTTP
Language-agnostic
Tool-based interface
Direct request/response handling

Connection:

text

Endpoint: https://mcp.tracemem.com
Protocol: JSON-RPC 2.0
Authentication: Agent API key

Available Tools:

decision_create - Create a new decision envelope
decision_get - Get decision status
decision_read - Read data through a Data Product
decision_write - Write data through a Data Product
decision_evaluate - Evaluate a policy
decision_request_approval - Request human approval
decision_add_context - Add context event to trace
decision_close - Close decision (commit or rollback)
decision_trace - Get complete trace (self-access only)
products_list - List available Data Products
product_get - Get Data Product details

Future: Language-Specific SDKs

SDKs for different programming languages are planned. They will provide:

Higher-level abstractions
Type safety
Convenience methods
Better developer experience

SDKs will provide the same functionality as Agent MCP with more convenience, but the underlying governance and audit capabilities remain the same.

Agent Workflow

A typical agent workflow follows this pattern:

Rendering diagram...

1. Create Decision Envelope

Every agent operation must start with a Decision Envelope:

python

decision = agent.create_decision(
    intent="customer.order.create",
    automation_mode="propose",
    actor="order-processing-agent"
)

The envelope captures:

Intent - Why this decision exists
Automation Mode - How it's executed (propose, approve, override, autonomous)
Actor - Who is making the decision

2. Read Data

Agents read data through Data Products, never directly:

python

customer = agent.read(
    decision_id=decision.id,
    product="customer_data",
    purpose="order_processing",
    query={"customer_id": "123"}
)

Key points:

Must specify a purpose that's in the Data Product's allowed purposes
Query filters data (minimize what you read)
Returns data according to Data Product's exposed schema
All access is logged in the decision trace

3. Evaluate Policies

Before taking action, agents evaluate policies:

python

policy_result = agent.evaluate_policy(
    decision_id=decision.id,
    policy_id="discount_cap_v1",
    inputs={
        "proposed_discount": 0.25,
        "customer_tier": "enterprise"
    }
)

Possible outcomes:

allow - Action is permitted
deny - Action is blocked
requires_exception - Human approval needed

4. Request Approvals

When policies require exceptions:

python

approval = agent.request_approval(
    decision_id=decision.id,
    title="25% Discount Approval",
    message="Customer requesting 25% discount...",
    require_rationale=True,
    expires_in_seconds=3600
)

# Poll for approval status
while True:
    status = agent.get_decision(decision.id).status
    if status == "approved":
        break
    elif status == "rejected":
        agent.close_decision(decision.id, action="rollback")
        return
    time.sleep(5)

5. Write Data

After governance checks pass, agents write data:

python

result = agent.write(
    decision_id=decision.id,
    product="orders",
    purpose="order_creation",
    mutation={
        "operation": "insert",
        "records": [{"customer_id": "123", "total": 1000.00}]
    }
)

Important: Writes are only committed when the decision is closed with "commit". If approval is required, writes are blocked until approved.

6. Close Decision

Always close decisions explicitly:

python

# Commit on success
agent.close_decision(
    decision_id=decision.id,
    action="commit",
    summary={"order_created": True}
)

# Or rollback on failure
agent.close_decision(
    decision_id=decision.id,
    action="rollback",
    summary={"reason": "Policy denied"}
)

Agent Capabilities

Data Access

Agents can:

Read data through Data Products with explicit purposes
Write data through Data Products after governance checks
List available Data Products
Get Data Product details and schemas

Agents cannot:

Access data directly (must use Data Products)
Bypass purpose restrictions
Access data without a Decision Envelope

Policy Evaluation

Agents can:

Evaluate policies with explicit inputs
Receive structured outcomes (allow, deny, requires_exception)
Get policy rationale

Agents cannot:

Modify policies
Bypass policy evaluations
Authorize actions themselves

Approval Workflow

Agents can:

Request approvals when policies require exceptions
Poll for approval status
Receive approval resolutions

Agents cannot:

Approve their own requests
Bypass approval requirements
Modify approval decisions

Context Events

Agents can:

Add context events to traces
Store agent reasoning, confidence scores, model metadata
Record intermediate decision points

This helps explain agent behavior later during audits.

Security Model

Trust Boundaries

TraceMem treats agents as untrusted by default:

Agent code is not trusted
Agent logic may be buggy, malicious, or misconfigured
Agents may attempt unsafe shortcuts

Key guarantee:

Agents can request actions, never authorize them.

Authentication

Agents authenticate using Agent API keys:

Tenant-scoped
Grant access to specific Data Products (read/write permissions)
Provide policy evaluation capabilities
Enable approval request channels

API keys are:

Created in the TraceMem dashboard
Shown only once (must be saved securely)
Rotatable and revocable
Separate for dev/staging/production

Authorization

TraceMem enforces authorization at multiple levels:

API Key Scope - What Data Products the agent can access
Data Product Permissions - What operations are allowed (read, insert, update, delete)
Purpose Restrictions - What purposes are allowed for data access
Policy Evaluations - Whether actions are allowed
Approval Requirements - Whether human approval is needed

Agents cannot bypass any of these checks.

Agent Types and Patterns

Autonomous Agents

Agents that execute without human approval:

python

decision = agent.create_decision(
    intent="support.ticket.route",
    automation_mode="autonomous"
)

Use when:

Actions are low-risk
Policies can fully govern the decision
No exceptions are expected

Propose Agents

Agents that propose actions for human review:

python

decision = agent.create_decision(
    intent="renewal.discount.evaluate",
    automation_mode="propose"
)

Use when:

Actions need human judgment
Policies may require exceptions
Human oversight is desired

Approval-Required Agents

Agents that require approval before execution:

python

decision = agent.create_decision(
    intent="financial.transaction.execute",
    automation_mode="approve"
)

Use when:

Actions have financial or legal consequences
Policies always require approval
Human authorization is mandatory

Best Practices

Always close decisions - Commit or rollback explicitly, never leave decisions open
Use meaningful intents - Follow hierarchical patterns (e.g., customer.order.create)
Specify explicit purposes - Use specific purposes for data access
Evaluate policies before actions - Check policies before performing actions
Handle all policy outcomes - Handle allow, deny, and requires_exception
Use try-finally patterns - Ensure decisions are closed even on errors
Store context events - Record agent reasoning for auditability
Use idempotency keys - For writes that may retry
Poll for approvals correctly - Handle timeouts and rejections
Minimize data access - Only read what you need, filter by ID when possible

Error Handling

Agents must handle errors gracefully:

python

decision_id = None
try:
    decision = agent.create_decision(...)
    decision_id = decision.id
    
    # ... perform operations ...
    
    agent.close_decision(decision_id, action="commit")
    
except Exception as e:
    # Always close on error
    if decision_id:
        agent.close_decision(decision_id, action="rollback")
    raise

Common errors:

Policy denial → Close with rollback
Approval rejection → Close with rollback
Approval timeout → Close with rollback
Data access denied → Close with rollback
Invalid request → Fix and retry

Relationship to Other Concepts

Decision Envelopes - Agents create and manage Decision Envelopes
Data Products - Agents access data exclusively through Data Products
Policies - Agents evaluate policies but cannot modify them
Approvals - Agents request approvals but cannot grant them
Decision Traces - Agents create traces automatically through their operations
Connectors - Agents don't interact with Connectors directly (Data Products handle this)

Mental Model

The Agent is the driver.
TraceMem is the road with guardrails, traffic lights, and speed limits.
The Agent decides where to go, but TraceMem ensures the journey is safe, legal, and recorded.
The Agent can request to turn, but TraceMem checks if the turn is allowed.
The Agent can request to speed up, but TraceMem enforces the speed limit.
At the end of the journey, TraceMem provides a complete record of where the Agent went, why it was allowed, and what happened along the way.

Agents

What Agents Are

What Agents Are Not

Agent Responsibilities

How Agents Interact with TraceMem

Current: Agent MCP (Model Context Protocol)

Future: Language-Specific SDKs

Agent Workflow

1. Create Decision Envelope

2. Read Data

3. Evaluate Policies

4. Request Approvals

5. Write Data

6. Close Decision

Agent Capabilities

Data Access

Policy Evaluation

Approval Workflow

Context Events

Security Model

Trust Boundaries

Authentication

Authorization

Agent Types and Patterns

Autonomous Agents

Propose Agents

Approval-Required Agents

Best Practices

Error Handling

Relationship to Other Concepts

Mental Model

Related Topics

Next Steps