letta-code-sdk/examples/research-team/README.md

Research Team Demo

A multi-agent academic research system built on the Letta Code SDK. Demonstrates persistent memory and collaborative agents that learn and improve over time.

Overview

This demo showcases Letta's key differentiator: agents with persistent memory that get better with use.

The research team consists of four specialized agents:

• 📚 Researcher - Finds and evaluates academic sources
• 🔍 Analyst - Synthesizes findings, identifies patterns
• ✍️ Writer - Produces polished research reports
• 🎯 Coordinator - Orchestrates workflow, manages quality

Each agent maintains memory blocks that persist across sessions, allowing them to:

• Remember which sources are reliable
• Apply effective search and analysis strategies
• Adapt writing style based on user feedback
• Build a shared knowledge base over time

Quick Start

# Set CLI path (required)
export LETTA_CLI_PATH=/path/to/letta-code-prod/letta.js

# Run a research task
cd examples/research-team
bun cli.ts "quantum error correction techniques" --depth=quick

# View team status
bun cli.ts --status

# Provide feedback (helps agents learn!)
bun cli.ts --feedback=task-1234567890-abc123

Commands

Research Query

bun cli.ts "your research query" [--depth=LEVEL]

Depth Levels:

Level	Sources	Time	Report Length
quick	3	~5 min	500-800 words
standard	6	~15 min	1000-1500 words
comprehensive	10	~30 min	2000-3000 words

Team Management

# View agent IDs and task count
bun cli.ts --status

# Reset team (start fresh)
bun cli.ts --reset

# Provide feedback on a task
bun cli.ts --feedback=<taskId>

How Learning Works

1. Quality Metrics (Automatic)

Each agent tracks quality metrics internally:

• Researcher: Source reliability scores, search strategy effectiveness
• Analyst: Synthesis coherence, citation accuracy
• Writer: Report completeness, structure effectiveness

2. User Feedback (Interactive)

After each task, you can provide a 1-5 star rating and optional comment:

bun cli.ts --feedback=task-1234567890-abc123
# Rate the research (1-5 stars): 4
# What could be better?: More focus on practical applications

3. Agent Reflections

When you provide feedback, each agent reflects on the task:

• What worked well?
• What could be improved?
• What lessons to apply next time?

These reflections are stored in memory and applied to future tasks.

4. Shared Knowledge Base

Agents share knowledge through memory blocks:

• High-quality sources added to shared source list
• Effective patterns documented for team reference
• Common pitfalls recorded to avoid repeated mistakes

File Structure

research-team/
├── cli.ts                    # Main CLI entry point
├── teleport-example.ts       # Agent teleportation demo
├── types.ts                  # Shared type definitions
├── agents/
│   ├── coordinator.ts        # Workflow orchestration
│   ├── researcher.ts         # Source finding & evaluation
│   ├── analyst.ts            # Synthesis & pattern identification
│   └── writer.ts             # Report generation
├── tools/
│   ├── mock-sources.ts       # Simulated academic papers (fallback)
│   └── file-store.ts         # File I/O helpers
├── output/                   # Research artifacts
│   ├── team-state.json       # Persisted agent IDs
│   ├── *-findings.md         # Researcher output
│   ├── *-analysis.md         # Analyst output
│   └── *-report.md           # Final reports
└── README.md

Example Session

First Task

$ bun cli.ts "large language model reasoning" --depth=standard

═══════════════════════════════════════════════════════════════
🔬 RESEARCH TEAM
═══════════════════════════════════════════════════════════════

📋 Query: "large language model reasoning"
📊 Depth: standard (est. 15 min)
📚 Target Sources: 6

────────────────────────────────────────────────────────────────

[Init] Starting research task: task-1704585600000-abc123
[Research] Initializing researcher agent...
[Research] Created new researcher agent: agent-xxx-yyy
[Research] Searching for 6 sources...
[Research] Found 6 sources
[Analysis] Initializing analyst agent...
[Analysis] Created new analyst agent: agent-aaa-bbb
[Analysis] Synthesizing findings...
[Writing] Initializing writer agent...
[Writing] Created new writer agent: agent-ccc-ddd
[Writing] Writing final report...
[Complete] Research complete in 12m 34s

═══════════════════════════════════════════════════════════════
✅ RESEARCH COMPLETE
═══════════════════════════════════════════════════════════════

⏱️  Duration: 12m 34s
📄 Report: examples/research-team/output/task-xxx-report.md
🔖 Task ID: task-1704585600000-abc123

💬 To provide feedback and help the team learn:
   bun cli.ts --feedback=task-1704585600000-abc123

Providing Feedback

$ bun cli.ts --feedback=task-1704585600000-abc123

📝 Feedback for Task: task-1704585600000-abc123
────────────────────────────────────────────────
Rate the research (1-5 stars): 4
What could be better?: Could use more recent sources

📤 Submitting feedback to team...

[Feedback] Processing feedback and triggering reflections...
[Feedback] Researcher reflecting...
[Researcher] I'll prioritize more recent publications in my search...
[Feedback] Analyst reflecting...
[Analyst] I'll pay more attention to temporal trends in my analysis...
[Feedback] Writer reflecting...
[Writer] I'll highlight publication dates more prominently...

✅ Feedback recorded! The team will apply these lessons to future tasks.

Second Task (Improved!)

$ bun cli.ts "chain of thought prompting" --depth=standard

# Agents now use their learned strategies:
# - Researcher prioritizes recent sources
# - Analyst notes temporal trends
# - Writer highlights dates

Agent Teleportation

This is Letta's killer feature: agents are portable entities, not just code constructs.

The research team agents you create here can be "teleported" into any context:

• 🖥️ CLI - Interactive debugging and testing
• 🌐 Web App - Embed in your product
• 🤖 GitHub Action - Automated PR reviews
• 💬 Slack Bot - Chat interface for your team
• 🔌 API Endpoint - Expose as a service

How It Works

import { resumeSession } from '@letta-ai/letta-code-sdk';

// Get agent ID from team-state.json or --status
const researcherAgentId = 'agent-xxx-yyy-zzz';

// Teleport the trained researcher into your code
const researcher = resumeSession(researcherAgentId, {
  allowedTools: ['web_search', 'Read', 'Write'],
  permissionMode: 'bypassPermissions',
});

// The agent remembers everything it learned!
// - Which sources are reliable
// - Effective search strategies
// - Domain knowledge from past research
await researcher.send('Find recent papers on quantum error correction');

Example: Research Team → API Endpoint

// server.ts - Turn your research team into an API
import express from 'express';
import { resumeSession } from '@letta-ai/letta-code-sdk';
import { loadTeamState } from './tools/file-store';

const app = express();
const teamState = await loadTeamState();

app.post('/research', async (req, res) => {
  const { query } = req.body;
  
  // Teleport the trained researcher
  const researcher = resumeSession(teamState.agentIds.researcher!, {
    permissionMode: 'bypassPermissions',
  });
  
  await researcher.send(`Research: ${query}`);
  
  let result = '';
  for await (const msg of researcher.receive()) {
    if (msg.type === 'assistant') result += msg.content;
  }
  
  researcher.close();
  res.json({ result });
});

// Your CLI-trained agents are now a production API!

View Agents in the Browser

Every agent has a web UI in the Letta ADE (Agent Development Environment):

https://app.letta.com/agents/<agent-id>

After running the demo, check --status for agent IDs, then click the links to:

• Inspect memory blocks
• View conversation history
• Chat with agents directly
• Edit agent configuration

Why This Matters

Claude Agent SDK	Letta Code SDK
Agents are ephemeral processes	Agents are persistent entities
Memory via local files	Memory on Letta server
Tied to one context	Teleport anywhere
Train in code only	Train anywhere (UI, CLI, API)

The story: A PM trains the research team by chatting in the web UI. A developer teleports those same agents into a CI pipeline. The agents bring all their learned knowledge with them.

Try It

After running the demo at least once, try the teleport example:

# First, create trained agents
bun cli.ts "large language models" --depth=quick

# Then teleport them into a different context
bun teleport-example.ts

This will:

1. Load the trained agent IDs from team-state.json
2. Teleport each agent into the script
3. Ask them what they've learned
4. Show how memories persist across contexts

---

Notes

Web Search

The Researcher agent uses the web_search tool to find real academic sources. No external API keys needed - it uses Letta's built-in search capability.

Agent Persistence

Agent IDs are stored in output/team-state.json. Running --reset clears this file and creates fresh agents on the next run. This is useful for:

• Starting over with clean memory
• Testing the "first run" experience
• Debugging agent behavior

Memory Block Contents

Each agent's memory blocks are stored on the Letta server. To inspect them:

1. Get the agent ID from --status or check the ADE links printed during execution
2. Visit https://app.letta.com/agents/<agent-id> to view memory contents

Extending the Demo

Add Real Web Search

Modify researcher.ts to call actual search APIs:

// In researcher.ts
import { web_search } from 'some-search-api';

// Replace mock search with real search
const sources = await web_search(query, { limit: config.sourcesCount });

Add More Domains

Extend mock-sources.ts with papers in new domains:

// In tools/mock-sources.ts
export const MOCK_SOURCES: AcademicSource[] = [
  // ... existing papers ...
  {
    id: 'econ-003',
    title: 'Your New Paper',
    authors: ['Author, A.'],
    // ...
  }
];

Customize Agent Prompts

Modify the system prompts in each agent file to change behavior:

• researcher.ts: Search strategy, quality criteria
• analyst.ts: Analysis framework, synthesis approach
• writer.ts: Writing style, report structure

License

Apache-2.0 (same as letta-code-sdk)