* 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>
829 lines
26 KiB
Plaintext
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>
|