Internal Attestations
Internal attestations are set by tools during workflow execution to prove that a step completed successfully. They enable sequential workflows where one operation must finish before another can begin.
Key Characteristics
Set by Tools
Internal attestations are created by tools as part of their execution. When a tool completes an operation, it can set an attestation to prove the operation occurred.
Immediately Active
Unlike external attestations, internal attestations don't require approval. They become active immediately upon creation and can be consumed right away.
Supports max_uses
Internal attestations can specify how many times they can be used. After reaching max_uses, the attestation is automatically consumed.
No Approval Required
Internal attestations do not use approval_criteria. They are trusted because they come from authenticated tools within the workflow.
Fields Reference
| Field | Type | Description |
|---|---|---|
| key | string | Unique identifier for the attestation |
| value | any | Arbitrary data stored with the attestation |
| max_uses | int | Maximum times this attestation can be consumed |
| one_time | bool | If true, consumed after first use (equivalent to max_uses=1) |
| time_to_live | int | Time-to-live in seconds before expiration |
| use_count | int | Current number of times the attestation has been used |
| timestamp | float | Unix timestamp when the attestation was created |
Internal-Only Field
The max_uses field is only available for internal attestations. External attestations do not support this field - they useone_time instead for single-use behavior.
Setting Internal Attestations
Tools set internal attestations using the attestations.set() method in the authenticated context:
# In a tool implementation
def execute(self, context: AuthenticatedContext, params: dict):
# Perform the operation
result = self.read_file(params["path"])
# Set attestation to prove the operation completed
context.attestations.set(
key="file_read_complete",
value={
"file": params["path"],
"bytes": len(result),
"hash": compute_hash(result)
},
max_uses=3, # Can be consumed up to 3 times
time_to_live=3600 # Expires in 1 hour
)
return resultSingle-Use Pattern
# Attestation consumed after first use
context.attestations.set(
key="payment_processed",
value={"transaction_id": "tx_123"},
one_time=True
)Multi-Use Pattern
# Attestation can be used 5 times
context.attestations.set(
key="api_quota_token",
value={"remaining": 5},
max_uses=5
)Consuming Internal Attestations
Attestations are consumed automatically when a policy requires them. The policy engine checks for the attestation and decrements the use count:
# Policy requiring the attestation
name: "write_requires_read"
description: "Writing to a file requires reading it first"
rules:
- resource: "file:write:*"
effect: allow
attestations:
- key: "file_read_complete"
required: trueWorkflow Execution:
1. Tool A: read_file("/data/report.csv")
│
▼
Sets attestation: "file_read_complete"
(max_uses: 3, use_count: 0)
│
▼
2. Tool B: write_file("/data/report.csv")
│
▼
Policy checks: "file_read_complete" exists? ✓
Consumes attestation (use_count: 1)
│
▼
3. Tool C: write_file("/data/report.csv")
│
▼
Policy checks: "file_read_complete" exists? ✓
Consumes attestation (use_count: 2)
│
▼
...after 3 uses, attestation is consumed and removedLifecycle
┌─────────────────┐
│ Tool Execution │
└────────┬────────┘
│
▼
┌─────────────────┐
│ attestations. │
│ set(key, value) │
└────────┬────────┘
│
▼
┌─────────────────┐
│ [Active] │
│ use_count: 0 │
└────────┬────────┘
│
┌────────────────┼────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Consumed │ │ Consumed │ │ Expired │
│ (one_time) │ │ (max_uses) │ │(time_to_live)│
└─────────────┘ └─────────────┘ └─────────────┘Internal attestations are removed when they are fully consumed (all uses exhausted) or when their time_to_live expires, whichever comes first.
Common Use Cases
Sequential Workflows
Ensure operations happen in order. A write operation can require that a read operation completed first.
Validation Gates
A validation tool sets an attestation after checking data integrity. Downstream operations require the validation attestation.
Resource Quotas
Use max_uses to implement quota systems. An attestation grants N operations before requiring renewal.
Time-Limited Access
Use time_to_live to create temporary access windows. The attestation expires automatically after the specified duration.
Best Practices
- -Use descriptive keys: Name attestations clearly (e.g.,
file_read_completenotstep1) - -Include relevant data: Store information in the value that helps with auditing (file paths, hashes, timestamps)
- -Set appropriate time_to_live: Don't let attestations live forever. Set values that match your workflow timing
- -Use max_uses for quotas: When you need to limit how many times an operation can occur, use
max_uses - -Prefer one_time for single operations: Use
one_time=Trueinstead ofmax_uses=1for clarity