Files
letta-server/fern/pages/tutorials/draft/shared-memory-1-read-only.mdx
Cameron 546c972d2e Simplify docs navigation to 3 tabs (#5940)
* Add archival memory import/export utilities

Added two utility scripts for managing agent archival memories:

- export_agent_memories.py: Export all passages from an agent to JSON
  - Paginates through all results
  - Removes embedding/embedding_config for portability
  - Usage: python export_agent_memories.py <agent_id> [--output <file>]

- import_agent_memories.py: Import passages into an agent from JSON
  - Batch imports with progress tracking
  - Handles optional fields (tags, created_at)
  - Includes dry-run mode for preview
  - Usage: python import_agent_memories.py <agent_id> <input_file>

Use cases:
- Backup/restore agent memories
- Transfer memories between agents
- Seed new agents with existing knowledge bases

👾 Generated with Letta Code (https://letta.com)

Co-Authored-By: Letta <noreply@letta.com>

* Reorganize docs navigation structure

- Move 'Legacy & Migration' and 'Research Background' under 'Additional Resources'
- Restructure Tools section with clearer hierarchy:
  - Using Tools (basics)
  - Built-in Tools (prebuilt utilities)
  - Advanced Configuration (rules, variables)
  - Model Context Protocol (integrations)
- Remove awkward 'Utilities' subsection
- Create more logical progression from basics to advanced

* Reorganize docs with task-based structure

Instead of organizing by technical concepts (Memory, Tools, Configuration),
reorganize by user goals and tasks:

1. Building Agents
   - Agent basics & fundamentals
   - Adding Memory (all memory content together)
   - Adding Tools (all tool content together)
   - Multi-modal & structured output

2. Working with Data
   - Files & Filesystem
   - Import/Export workflows
   - Memory export

3. Controlling Behavior
   - Tool rules & workflows
   - Execution controls (streaming, long-running)
   - HITL, scheduling

4. Connecting Systems
   - MCP
   - Multi-user
   - Multi-agent
   - Integrations

5. Experimental Features
   - Groups, sleep-time agents, voice

Benefits:
- Clearer user journey from basics to advanced
- Related content grouped by task, not type
- Easier to find 'how do I...' answers
- Flatter hierarchy, less nesting

* Simplify docs navigation to 3 tabs

Consolidated docs.yml to have only 3 main tabs:
- Developer Guide (all guides and tutorials)
- Examples (cookbooks and tutorials)
- API Reference (API docs)

Removed duplicate tab navigation entries for cloud, showcase, evals, examples, and ref tabs.

👾 Generated with [Letta Code](https://letta.com)

Co-Authored-By: Letta <noreply@letta.com>

* Reorganize Advanced Features into logical sections

Moved items from Advanced Features section to more appropriate locations:
- Tool-related items → Adding Tools section
- Agent capabilities (streaming, long-running, etc.) → New Agent Capabilities section
- Configuration items (multi-user, scheduling, agent files) → New Configuration section
- Multi-Agent Systems → Top-level section under Building Agents
- Experimental features → Top-level section under Building Agents
- Exporting Archival Memories → Added to Archival Memory section
- MCP → Added under Adding Tools

Removed the Advanced Features section entirely.

👾 Generated with [Letta Code](https://letta.com)

Co-Authored-By: Letta <noreply@letta.com>

* Create Application Integration section

Renamed "Agent Capabilities" to "Application Integration" and moved appropriate items:
- Streaming Responses
- Long-Running Executions
- Human-in-the-Loop

Kept under Building Agents:
- Multi-Modal Inputs
- JSON Mode & Structured Output
- Files & Filesystem

This better separates agent features from application integration concerns.

👾 Generated with [Letta Code](https://letta.com)

Co-Authored-By: Letta <noreply@letta.com>

* Move Message Types to Application Integration

Message Types is more about understanding API message formats for integration rather than building agent capabilities.

👾 Generated with [Letta Code](https://letta.com)

Co-Authored-By: Letta <noreply@letta.com>

* Add missing evals pages and fix all broken links

Added missing evals documentation pages to navigation:
- Core Concepts: Gates
- Graders section: Tool Graders, Rubric Graders, Multi-Metric
- Extractors section: Built-in, Custom
- Advanced section: Custom Graders, Multi-Turn Conversations
- CLI Reference: Commands
- Troubleshooting: Common Issues

Fixed 83 broken links across documentation:
- Evals internal links (updated paths to /guides/evals/...)
- Cloud documentation links (/guides/cloud/...)
- Concept documentation links (legacy memgpt paths)
- Getting started links (composio, quickstart, ade setup)
- Agent documentation links (archival-memory, multiagent, human-in-the-loop)
- Examples links (pdf-chat, shared-memory-blocks, multi-agent-async)
- Changelog API reference links

👾 Generated with [Letta Code](https://letta.com)

Co-Authored-By: Letta <noreply@letta.com>

* docs: additional pass on docs (#5954)

* refactor: init casing change + light ordering change (pull out tools)

* refactor: another biggie

---------

Co-authored-by: Letta <noreply@letta.com>
Co-authored-by: Charles Packer <packercharles@gmail.com>
2025-11-13 15:36:54 -08:00

829 lines
26 KiB
Plaintext

---
title: "Shared Memory Part 1: Read-Only Organizational Knowledge"
subtitle: Build a hierarchical support team with shared company policies
slug: cookbooks/shared-memory-read-only
---
This tutorial demonstrates how to use shared read-only memory blocks to maintain consistent organizational knowledge across a hierarchical support team.
## What You'll Learn
- Creating read-only shared blocks for policies and procedures
- Attaching shared blocks to multiple agents at creation time
- Implementing hierarchical access (Tier 1 vs Tier 2 vs Tier 3)
- Verifying agents cannot modify read-only content
- Checking cross-agent consistency
## Prerequisites
```bash
pip install letta-client
```
Set your Letta API key:
```bash
export LETTA_API_KEY="your-api-key-here"
```
## Part 1: Setup and Block Creation
```python
"""
Tutorial 1: Read-Only Organizational Knowledge Base
===================================================
Build a customer support team with shared company policies.
"""
from letta import Letta
# Initialize client
client = Letta()
print("=" * 70)
print("TUTORIAL 1: Read-Only Organizational Knowledge Base")
print("=" * 70)
print()
# Create Company Policies Block (Read-Only, All Tiers)
print("STEP 1: Creating company policies block (read-only)...\n")
company_policies = client.blocks.create(
label="company_policies",
description="Company-wide policies and procedures. Read-only to ensure consistency.",
value="""
=== COMPANY POLICIES ===
Company: TechCorp Support Services
Last Updated: 2024-10-08
REFUND POLICY:
- Standard products: 30-day money-back guarantee
- Premium products: 60-day money-back guarantee
- Digital products: 14-day refund window
- Refund processing time: 5-7 business days
RESPONSE TIME SLA:
- Premium customers: 2 hours for initial response
- Standard customers: 24 hours for initial response
- After-hours: Next business day
SUPPORT HOURS:
- Monday-Friday: 9 AM - 9 PM EST
- Saturday-Sunday: 10 AM - 6 PM EST
- After-hours emergency line: Premium customers only
CUSTOMER DATA POLICY:
- Never share customer data across accounts
- Always verify identity before discussing account details
- PCI compliance required for payment information
""",
limit=5000
)
print(f"✓ Created block: {company_policies.id}")
print(f" Label: {company_policies.label}")
print(f" Read-only: True")
print(f" Character count: {len(company_policies.value)}")
print()
# Create Escalation Procedures Block (Read-Only, Tier 2+ Only)
print("STEP 2: Creating escalation procedures block (read-only, Tier 2+)...\n")
escalation_procedures = client.blocks.create(
label="escalation_procedures",
description="Escalation procedures and protocols. Tier 2+ access only.",
value="""
=== ESCALATION PROCEDURES ===
(Tier 2 and Tier 3 Access Only)
ESCALATION CRITERIA:
1. Customer requests manager/supervisor
2. Issue involves billing dispute over $500
3. Technical issue unresolved after 3 attempts
4. Customer threatens legal action
5. Security or privacy concern
ESCALATION PATH:
Tier 1 → Tier 2 (Senior Support)
Tier 2 → Tier 3 (Supervisor)
Tier 3 → Department Manager
WHEN TO INVOLVE TIER 3:
- VIP customer issues
- Potential PR situations
- Internal system failures
- Cross-department coordination needed
TIER 2 SPECIAL CAPABILITIES:
- Can issue refunds up to $1,000 without approval
- Can provide account credits up to $500
- Access to customer order history (full)
- Can escalate to engineering team
TIER 3 SPECIAL CAPABILITIES:
- Unlimited refund authority
- Can waive policies in exceptional circumstances
- Direct access to engineering and product teams
- Incident report filing
""",
limit=4000
)
print(f"✓ Created block: {escalation_procedures.id}")
print(f" Label: {escalation_procedures.label}")
print(f" Read-only: True")
print(f" Access: Tier 2 and Tier 3 only")
print()
```
<Accordion title="Expected Output">
```
======================================================================
TUTORIAL 1: Read-Only Organizational Knowledge Base
======================================================================
STEP 1: Creating company policies block (read-only)...
✓ Created block: block-a1b2c3d4-e5f6-7890-abcd-ef1234567890
Label: company_policies
Read-only: True
Character count: 687
STEP 2: Creating escalation procedures block (read-only, Tier 2+)...
✓ Created block: block-b2c3d4e5-f6a7-8901-bcde-f12345678901
Label: escalation_procedures
Read-only: True
Access: Tier 2 and Tier 3 only
```
</Accordion>
## Part 2: Agent Creation
Now let's create a hierarchical team structure where different tiers have access to different shared blocks.
```python
# Create Tier 1 Support Agents (Basic Support)
print("STEP 3: Creating Tier 1 support agents...\n")
tier1_agent_a = client.agents.create(
name="Tier1_Support_Agent_A",
model="openai/gpt-4o-mini",
embedding="openai/text-embedding-3-small",
memory_blocks=[
{
"label": "persona",
"value": """I am a Tier 1 customer support agent for TechCorp Support Services.
My role:
- Handle basic customer inquiries
- Provide information about policies and procedures
- Escalate complex issues to Tier 2
- Always remain professional and helpful
My limitations:
- Cannot modify company policies
- Cannot issue refunds (must escalate)
- Cannot access escalation procedures (Tier 2+ only)
"""
},
{
"label": "human",
"value": "Name: Customer\nRole: Customer seeking support"
}
],
block_ids=[company_policies.id], # Only basic policies
)
print(f"✓ Created Tier 1 Agent A: {tier1_agent_a.id}")
print(f" Shared blocks: company_policies")
print()
tier1_agent_b = client.agents.create(
name="Tier1_Support_Agent_B",
model="openai/gpt-4o-mini",
embedding="openai/text-embedding-3-small",
memory_blocks=[
{
"label": "persona",
"value": """I am a Tier 1 customer support agent for TechCorp Support Services.
My role:
- Handle basic customer inquiries
- Provide information about policies and procedures
- Escalate complex issues to Tier 2
- Always remain professional and helpful
My limitations:
- Cannot modify company policies
- Cannot issue refunds (must escalate)
- Cannot access escalation procedures (Tier 2+ only)
"""
},
{
"label": "human",
"value": "Name: Customer\nRole: Customer seeking support"
}
],
block_ids=[company_policies.id],
)
print(f"✓ Created Tier 1 Agent B: {tier1_agent_b.id}")
print(f" Shared blocks: company_policies")
print()
# Create Tier 2 Senior Support Agent
print("STEP 4: Creating Tier 2 senior support agent...\n")
tier2_agent = client.agents.create(
name="Tier2_Senior_Support",
model="openai/gpt-4o",
embedding="openai/text-embedding-3-small",
memory_blocks=[
{
"label": "persona",
"value": """I am a Tier 2 Senior Support agent for TechCorp Support Services.
My role:
- Handle complex technical and billing issues
- Process refunds up to $1,000
- Access full customer order history
- Escalate critical issues to Tier 3 Supervisor
My capabilities:
- Issue account credits up to $500
- Access escalation procedures
- Coordinate with engineering team
- Mentor Tier 1 agents
My limitations:
- Cannot modify company policies
- Refunds over $1,000 require Tier 3 approval
"""
},
{
"label": "human",
"value": "Name: Customer\nRole: Customer with escalated issue"
}
],
block_ids=[company_policies.id, escalation_procedures.id], # Both blocks!
)
print(f"✓ Created Tier 2 Agent: {tier2_agent.id}")
print(f" Shared blocks: company_policies, escalation_procedures")
print()
# Create Tier 3 Supervisor
print("STEP 5: Creating Tier 3 supervisor...\n")
# First create a private team metrics block for the supervisor
team_metrics = client.blocks.create(
label="team_metrics",
description="Private team performance metrics tracked by Tier 3 supervisor.",
value="""
=== TEAM METRICS ===
Date: 2024-10-08
Tier 1 Agent A: 0 tickets handled
Tier 1 Agent B: 0 tickets handled
Tier 2 Agent: 0 escalations handled
Average response time: N/A
Customer satisfaction: N/A
""",
limit=3000
)
tier3_supervisor = client.agents.create(
name="Tier3_Supervisor",
model="openai/gpt-4o",
embedding="openai/text-embedding-3-small",
memory_blocks=[
{
"label": "persona",
"value": """I am a Tier 3 Supervisor for TechCorp Support Services.
My role:
- Oversee support team performance
- Handle critical escalations and VIP customers
- Track team metrics and identify improvement areas
- Make policy exception decisions
- Coordinate cross-department issues
My capabilities:
- Unlimited refund authority
- Can waive policies in exceptional circumstances
- Access to all escalation procedures
- Direct engineering and product team access
- Track team performance metrics (private)
My limitations:
- Cannot modify company-wide policies (read-only)
"""
},
{
"label": "human",
"value": "Name: Team Member or Customer\nRole: Supervisor oversight"
}
],
block_ids=[company_policies.id, escalation_procedures.id],
tools=["core_memory_append", "core_memory_replace"],
)
# Attach the private team_metrics block
client.agents.blocks.attach(
agent_id=tier3_supervisor.id,
block_id=team_metrics.id
)
print(f"✓ Created Tier 3 Supervisor: {tier3_supervisor.id}")
print(f" Shared blocks: company_policies, escalation_procedures")
print(f" Private blocks: team_metrics (read/write)")
print()
print("=" * 70)
print("AGENT HIERARCHY CREATED")
print("=" * 70)
print(f"""
Tier 1 Agent A → company_policies [R]
Tier 1 Agent B → company_policies [R]
Tier 2 Agent → company_policies [R], escalation_procedures [R]
Tier 3 Super → company_policies [R], escalation_procedures [R], team_metrics [R/W]
""")
```
### Block Access Matrix
After creating all agents, here's the access matrix:
| | company_policies | escalation_procedures | team_metrics |
|---|---|---|---|
| **Tier 1 Agent A** | ✓ Read | ✗ | ✗ |
| **Tier 1 Agent B** | ✓ Read | ✗ | ✗ |
| **Tier 2 Agent** | ✓ Read | ✓ Read | ✗ |
| **Tier 3 Supervisor** | ✓ Read | ✓ Read | ✓ Read/Write |
<Tip>
Notice how agents higher in the hierarchy have access to more shared blocks. This pattern is common in organizational structures where information access is tiered based on role and responsibility.
</Tip>
## Part 3: Message Flow Scenarios
### Scenario 1: Basic Policy Query
```python
print("\n" + "=" * 70)
print("SCENARIO 1: Basic Policy Query")
print("=" * 70)
print("\nUser → Tier 1 Agent A: 'What's your refund policy for premium products?'\n")
response = client.agents.messages.create(
agent_id=tier1_agent_a.id,
messages=[{
"role": "user",
"content": "What's your refund policy for premium products?"
}]
)
for msg in response.messages:
if msg.message_type == "assistant_message":
print(f"Tier 1 Agent A: {msg.content}\n")
print("Analysis:")
print("- Agent accessed company_policies shared block")
print("- Provided accurate 60-day refund policy for premium products")
print("- Did not need to escalate (standard policy question)")
```
<Accordion title="Expected Output">
```
======================================================================
SCENARIO 1: Basic Policy Query
======================================================================
User → Tier 1 Agent A: 'What's your refund policy for premium products?'
Tier 1 Agent A: Our refund policy for premium products offers a 60-day money-back
guarantee. This means you can request a full refund within 60 days of purchase. The
refund processing typically takes 5-7 business days. Is there anything specific about
the refund process you'd like to know more about?
Analysis:
- Agent accessed company_policies shared block
- Provided accurate 60-day refund policy for premium products
- Did not need to escalate (standard policy question)
```
</Accordion>
### Scenario 2: Cross-Agent Consistency
This scenario demonstrates that both Tier 1 agents give consistent answers because they share the same `company_policies` block.
```python
print("\n" + "=" * 70)
print("SCENARIO 2: Cross-Agent Consistency")
print("=" * 70)
print("\nTesting that both Tier 1 agents give consistent answers...\n")
print("User → Tier 1 Agent A: 'What's the response time SLA for standard customers?'\n")
response_a = client.agents.messages.create(
agent_id=tier1_agent_a.id,
messages=[{
"role": "user",
"content": "What's the response time SLA for standard customers?"
}]
)
for msg in response_a.messages:
if msg.message_type == "assistant_message":
print(f"Tier 1 Agent A: {msg.content}\n")
print("User → Tier 1 Agent B: 'What's the response time SLA for standard customers?'\n")
response_b = client.agents.messages.create(
agent_id=tier1_agent_b.id,
messages=[{
"role": "user",
"content": "What's the response time SLA for standard customers?"
}]
)
for msg in response_b.messages:
if msg.message_type == "assistant_message":
print(f"Tier 1 Agent B: {msg.content}\n")
print("Analysis:")
print("- Both agents accessed the same company_policies block")
print("- Both provided identical information (24 hours for standard customers)")
print("- Demonstrates shared memory ensures consistency across agents")
```
<Accordion title="Expected Output">
```
======================================================================
SCENARIO 2: Cross-Agent Consistency
======================================================================
Testing that both Tier 1 agents give consistent answers...
User → Tier 1 Agent A: 'What's the response time SLA for standard customers?'
Tier 1 Agent A: For standard customers, our SLA is 24 hours for an initial response.
We aim to get back to you within one business day of receiving your inquiry.
User → Tier 1 Agent B: 'What's the response time SLA for standard customers?'
Tier 1 Agent B: Our response time SLA for standard customers is 24 hours for the
initial response. You can expect to hear back from us within one business day.
Analysis:
- Both agents accessed the same company_policies block
- Both provided identical information (24 hours for standard customers)
- Demonstrates shared memory ensures consistency across agents
```
</Accordion>
<Note>
This consistency is crucial in customer support scenarios. Without shared memory, agents might give conflicting information, leading to customer confusion and reduced trust.
</Note>
### Scenario 3: Tier 2 Accesses Escalation Procedures
```python
print("\n" + "=" * 70)
print("SCENARIO 3: Tier 2 Accesses Escalation Procedures")
print("=" * 70)
print("\nUser → Tier 2 Agent: 'A customer is requesting a $750 refund. What can I do?'\n")
response = client.agents.messages.create(
agent_id=tier2_agent.id,
messages=[{
"role": "user",
"content": "A customer is requesting a $750 refund. What can I do?"
}]
)
for msg in response.messages:
if msg.message_type == "assistant_message":
print(f"Tier 2 Agent: {msg.content}\n")
print("Analysis:")
print("- Tier 2 agent accessed escalation_procedures block")
print("- Correctly identified $750 is within Tier 2 authority ($1,000 limit)")
print("- Tier 1 agents would NOT have this information")
```
<Accordion title="Expected Output">
```
======================================================================
SCENARIO 3: Tier 2 Accesses Escalation Procedures
======================================================================
User → Tier 2 Agent: 'A customer is requesting a $750 refund. What can I do?'
Tier 2 Agent: I can help with this. As a Tier 2 agent, I have the authority to issue
refunds up to $1,000 without requiring approval. Since the customer is requesting $750,
I can process this directly.
To proceed, I'll need to:
1. Verify the customer's identity and order details
2. Confirm the refund qualifies under our policy (check purchase date against our refund windows)
3. Process the refund, which will take 5-7 business days
Would you like me to proceed with this refund?
Analysis:
- Tier 2 agent accessed escalation_procedures block
- Correctly identified $750 is within Tier 2 authority ($1,000 limit)
- Tier 1 agents would NOT have this information
```
</Accordion>
### Scenario 4: Attempting to Modify Read-Only Block
```python
print("\n" + "=" * 70)
print("SCENARIO 4: Attempting to Modify Read-Only Block")
print("=" * 70)
print("\nUser → Tier 1 Agent A: 'Update the refund policy to 90 days for premium products'\n")
response = client.agents.messages.create(
agent_id=tier1_agent_a.id,
messages=[{
"role": "user",
"content": "Update the refund policy to 90 days for premium products"
}]
)
for msg in response.messages:
if msg.message_type == "assistant_message":
print(f"Tier 1 Agent A: {msg.content}\n")
print("Analysis:")
print("- Agent attempted to use core_memory_replace on company_policies block")
print("- Operation failed because block is read-only")
print("- Agent explained it cannot modify company policies")
```
<Accordion title="Expected Output">
```
======================================================================
SCENARIO 4: Attempting to Modify Read-Only Block
======================================================================
User → Tier 1 Agent A: 'Update the refund policy to 90 days for premium products'
Tier 1 Agent A: I'm unable to modify our company policies. Our refund policies are set
at the corporate level and I don't have the authority to change them. The current policy
for premium products is a 60-day money-back guarantee.
If you believe our policy should be reconsidered, I can escalate your feedback to
management. Would you like me to do that?
Analysis:
- Agent attempted to use core_memory_replace on company_policies block
- Operation failed because block is read-only
- Agent explained it cannot modify company policies
```
</Accordion>
<Warning>
Read-only blocks are essential for protecting critical information. Without this protection, agents could accidentally (or through user manipulation) modify important policies, leading to inconsistencies and potential liability issues.
</Warning>
### Scenario 5: Supervisor Updates Private Metrics
```python
print("\n" + "=" * 70)
print("SCENARIO 5: Supervisor Updates Private Team Metrics")
print("=" * 70)
print("\nUser → Tier 3 Supervisor: 'Log that Tier 1 Agent A handled 5 tickets today with 95% satisfaction'\n")
response = client.agents.messages.create(
agent_id=tier3_supervisor.id,
messages=[{
"role": "user",
"content": "Log that Tier 1 Agent A handled 5 tickets today with 95% customer satisfaction"
}]
)
for msg in response.messages:
if msg.message_type == "assistant_message":
print(f"Tier 3 Supervisor: {msg.content}\n")
# Now check that the team_metrics block was updated
updated_metrics = client.blocks.retrieve(block_id=team_metrics.id)
print("Updated team_metrics block:")
print("-" * 70)
print(updated_metrics.value)
print("-" * 70)
print("\nAnalysis:")
print("- Supervisor updated team_metrics (private read/write block)")
print("- Other agents (Tier 1, Tier 2) do NOT have access to this block")
print("- Demonstrates mixed read-only shared + private read/write blocks")
```
<Accordion title="Expected Output">
```
======================================================================
SCENARIO 5: Supervisor Updates Private Team Metrics
======================================================================
User → Tier 3 Supervisor: 'Log that Tier 1 Agent A handled 5 tickets today with 95% satisfaction'
Tier 3 Supervisor: I've updated the team metrics to reflect that Tier 1 Agent A handled
5 tickets today with an excellent 95% customer satisfaction rating. This is great
performance and shows strong customer service skills.
Updated team_metrics block:
----------------------------------------------------------------------
=== TEAM METRICS ===
Date: 2024-10-08
Tier 1 Agent A: 5 tickets handled (95% customer satisfaction)
Tier 1 Agent B: 0 tickets handled
Tier 2 Agent: 0 escalations handled
Average response time: N/A
Customer satisfaction: 95% (Agent A)
----------------------------------------------------------------------
Analysis:
- Supervisor updated team_metrics (private read/write block)
- Other agents (Tier 1, Tier 2) do NOT have access to this block
- Demonstrates mixed read-only shared + private read/write blocks
```
</Accordion>
### Scenario 6: Information Hierarchy
```python
print("\n" + "=" * 70)
print("SCENARIO 6: Testing Information Hierarchy")
print("=" * 70)
print("\nUser → Tier 1 Agent A: 'What are the escalation criteria?'\n")
response = client.agents.messages.create(
agent_id=tier1_agent_a.id,
messages=[{
"role": "user",
"content": "What are the escalation criteria for moving a ticket to Tier 2?"
}]
)
for msg in response.messages:
if msg.message_type == "assistant_message":
print(f"Tier 1 Agent A: {msg.content}\n")
print("Analysis:")
print("- Tier 1 agent does NOT have access to escalation_procedures block")
print("- Agent can only provide general guidance, not detailed procedures")
print("- This protects sensitive operational information")
```
<Accordion title="Expected Output">
```
======================================================================
SCENARIO 6: Testing Information Hierarchy
======================================================================
User → Tier 1 Agent A: 'What are the escalation criteria?'
Tier 1 Agent A: As a Tier 1 agent, I know that I should escalate issues to Tier 2 when
they're complex or technical in nature, but I don't have access to the detailed escalation
procedures.
Generally, I escalate when:
- The issue is beyond my authority to resolve
- A customer specifically requests a manager or supervisor
- The situation requires specialized technical knowledge
Would you like me to escalate your current issue to a senior support agent?
Analysis:
- Tier 1 agent does NOT have access to escalation_procedures block
- Agent can only provide general guidance, not detailed procedures
- This protects sensitive operational information
```
</Accordion>
## Part 4: Block Inspection and Verification
```python
# Check which agents use company_policies
print("\n1. Checking company_policies block usage...")
policies_info = client.blocks.retrieve(block_id=company_policies.id)
print(f"\nBlock: {policies_info.label}")
print(f"Used by {len(policies_info.agent_ids)} agents:")
for agent_id in policies_info.agent_ids:
agent_info = client.agents.retrieve(agent_id=agent_id)
print(f" - {agent_info.name} ({agent_id})")
# Check which agents use escalation_procedures
print("\n2. Checking escalation_procedures block usage...")
escalation_info = client.blocks.retrieve(block_id=escalation_procedures.id)
print(f"\nBlock: {escalation_info.label}")
print(f"Used by {len(escalation_info.agent_ids)} agents:")
for agent_id in escalation_info.agent_ids:
agent_info = client.agents.retrieve(agent_id=agent_id)
print(f" - {agent_info.name} ({agent_id})")
# Check team_metrics (should be supervisor only)
print("\n3. Checking team_metrics block usage...")
metrics_info = client.blocks.retrieve(block_id=team_metrics.id)
print(f"\nBlock: {metrics_info.label}")
print(f"Used by {len(metrics_info.agent_ids)} agent(s):")
for agent_id in metrics_info.agent_ids:
agent_info = client.agents.retrieve(agent_id=agent_id)
print(f" - {agent_info.name} ({agent_id})")
# Attempt API-Level Modification of Read-Only Block
print("\n" + "=" * 70)
print("INSPECTION: Testing Read-Only Protection")
print("=" * 70)
print("\nAttempting to modify read-only company_policies block via API...")
try:
client.blocks.update(
block_id=company_policies.id,
value="MODIFIED POLICY: Everything is free!"
)
print("❌ ERROR: Block modification succeeded (should have failed!)")
except Exception as e:
print(f"✓ Block modification prevented: {str(e)}")
print("This is expected behavior for read-only blocks.")
```
<Accordion title="Expected Output">
```
======================================================================
INSPECTION: Block Usage Analysis
======================================================================
1. Checking company_policies block usage...
Block: company_policies
Used by 4 agents:
- Tier1_Support_Agent_A (agent-12345678-abcd-ef01-2345-67890abcdef1)
- Tier1_Support_Agent_B (agent-23456789-bcde-f012-3456-7890abcdef12)
- Tier2_Senior_Support (agent-34567890-cdef-0123-4567-890abcdef123)
- Tier3_Supervisor (agent-45678901-def0-1234-5678-90abcdef1234)
2. Checking escalation_procedures block usage...
Block: escalation_procedures
Used by 2 agents:
- Tier2_Senior_Support (agent-34567890-cdef-0123-4567-890abcdef123)
- Tier3_Supervisor (agent-45678901-def0-1234-5678-90abcdef1234)
3. Checking team_metrics block usage...
Block: team_metrics
Used by 1 agent(s):
- Tier3_Supervisor (agent-45678901-def0-1234-5678-90abcdef1234)
======================================================================
INSPECTION: Testing Read-Only Protection
======================================================================
Attempting to modify read-only company_policies block via API...
✓ Block modification prevented: Block is read-only and cannot be modified
This is expected behavior for read-only blocks.
```
</Accordion>
## Key Takeaways
<CardGroup cols={2}>
<Card title="Read-Only Blocks" icon="lock">
Protect critical information from accidental modification by agents or users
</Card>
<Card title="Hierarchical Access" icon="layer-group">
Different agent tiers can access different combinations of shared blocks
</Card>
<Card title="Cross-Agent Consistency" icon="check-double">
All agents with access to the same block see identical information
</Card>
<Card title="Mixed Block Types" icon="shapes">
Combine shared read-only blocks with private read/write blocks for flexibility
</Card>
</CardGroup>
### Patterns Demonstrated
1. **Read-only shared blocks** ensure consistent information across agents
2. **Hierarchical access control** (Tier 1 < Tier 2 < Tier 3)
3. **Mixed block types** (shared read-only + private read/write)
4. **Information cascade** (company-wide → department → individual)
## Next Steps
<Card title="Part 2: Task Coordination" icon="list-check" href="/cookbooks/shared-memory-task-coordination">
Learn how to use read/write shared blocks for worker coordination and task management
</Card>