Claude Quickstarts Reference Implementations

This repository contains several specialized quickstart implementations. Choose a project based on your target use case:

• Customer Support Agent: Demonstrates natural language understanding and generation with access to a knowledge base.
• Financial Data Analyst: Demonstrates interactive data visualization and financial data analysis via chat.
• Computer Use Demo: Provides an environment and tools for Claude to control a desktop computer (supports computer_use_20251124 tool version with zoom actions).
• Computer Use Best Practices: A native-macOS reference implementation (run in a VM!) demonstrating reliable patterns like explicit tool definitions, image pruning, prompt caching, and trajectory recording.
• Browser Use Demo: A reference implementation for browser automation using a Playwright-backed browser tool to navigate, inspect DOM, and fill forms.
• Autonomous Coding Agent: Uses the Claude Agent SDK to demonstrate a two-agent pattern (initializer + coding agent) for building applications with git-persisted progress.
• Managed Agents: Chat SDK: Pairs Claude Managed Agents with Vercel's Chat SDK for browser-based chat, research analysis, and multi-platform support (Slack, Teams, etc.).
• Managed Agents with CopilotKit and AG-UI: Demonstrates bridging managed-agent sessions to the AG-UI protocol and rendering tool calls as interactive generative UI components.
• Managed Agents: Knowledge Wiki: Demonstrates distilling a document corpus into a versioned memory-store knowledge wiki for efficient, provenance-backed querying.

This project integrates assistant-ui with Claude Managed Agents. The following files represent the core logic and architecture:

• Configuration & Provisioning:
  • setup/agent-config.ts: Defines the model, system prompt, tools (e.g., always_ask, show_chart), and environment.
  • setup/create-agent.ts: Handles one-time provisioning of the agent and its environment.
• Managed Agents Logic:
  • lib/managed-agents/reducer.ts: Converts the event log into messages.
  • lib/managed-agents/session-controller.ts: Manages per-session replay, live tail, sending/confirming/interrupting, and batched approvals.
  • lib/managed-agents/session-list-adapter.ts: Provides the RemoteThreadListAdapter for the sidebar.
  • lib/managed-agents/runtime-provider.tsx: Provides useRemoteThreadListRuntime and per-session useExternalStoreRuntime.
  • lib/managed-agents/attachments.ts: Handles Composer attachments via Files API upload and sandbox mounting.
• API & UI:
  • app/api/sessions/**: Route handlers for list, create, replay, tail, messages, confirm, files, and interrupt.
  • components/tool-uis/: Contains tool cards and the approval bar.
  • app/assistant.tsx: The main composed view containing the Sidebar, thread, toolkit, and suggestions.
• Security & Setup:
  • lib/owned-session.ts: Implements the session ownership gate for routes.
  • skill.md: Contains setup walkthroughs, debugging, and gotchas.

The computer-use-best-practices repository is organized into the following key components:

Core Logic (computer_use/)

• __main__.py: CLI entrypoint, handles build_tools() and build_system_prompt().
• loop.py: Manages the streaming sampling loop, retries, and advisor/compaction wiring.
• trajectory.py: Manages on-disk transcripts, images, and per-run scratch directories.
• tools/: Contains the tool implementations:
  • base.py: Defines Tool ABC and ToolCollection.
  • computer.py: Uses pyautogui for screen control (includes zoom and key aliasing).
  • browser.py: Uses playwright with headless Chromium.
  • shell.py: Provides a sandboxed bash and python environment with output caps.
  • editor.py: Allows viewing, creating, string replacement, and insertion within the scratch directory.

Configuration and UI

• constants.py: Contains the Config dataclass, cfg instance, prompts, and derived sets.
• config.example.toml: A template for overriding CU_CONFIG.
• dev_ui/: Contains developer tools like the trajectory_viewer (Streamlit) and tool_panel (FastAPI).

In this architecture, the conversation ID used by the Chat SDK is identical to the Managed Agents session ID.

• Session Creation: The page creates a session via POST /api/sessions (calling sessions.create()) and passes the returned ID to useChat as the threadId.
• Storage: The Managed Agents API acts as the entire conversation store.
  • Sidebar lists sessions via sessions.list({ agent_id }).
  • Replaying a chat uses sessions.events.list() to turn user.message and agent.message events back into chat bubbles.
  • The first message of a conversation is used as the title via sessions.update().
• Data Persistence: The server is stateless regarding Chat SDK internals. createMemoryState() in src/bot.ts handles message dedup and locks, but persistMessageHistory: false ensures the adapter doesn't cache message bodies, leaving the live transcript in the browser and the durable transcript in the Managed Agents session.

To manage the high token cost of screenshot-heavy trajectories, the project uses two primary mechanisms:

Prompt Caching

loop.py applies cache_control: {"type": "ephemeral"} breakpoints to the system prompt and the final tool-result block of the most recent user turn. This allows subsequent calls to serve the prefix from cache, reducing latency and cost.

Image Pruning Strategies

Because prompt caching requires a byte-identical prefix, naive pruning (like keeping only the last N images) causes cache misses every turn. The project provides three strategies via cfg.image_prune_strategy:

• "interval" (Default): Keeps the image count stable for cfg.image_prune_interval turns. This ensures the prefix remains identical, allowing the cache to hit consistently. This is recommended for long, visual tasks.
• "none": Disables pruning. Best for short, screenshot-light tasks where the cost of re-processing a few extra images is lower than the cost of a cache invalidation.
• "simple": Keeps the last N images. This is "cache-hostile" because the prefix changes every turn.

Pruning vs. Autocompaction (Summarization)

• Summarization (enable_autocompaction): A server-side event that condenses the conversation into a summary. It is more expensive (extra API turn) and causes a cold cache, but preserves more textual information.
• Pruning: Faster and cheaper in the short term. It is most effective when it prevents the conversation from hitting the autocompaction_trigger_tokens threshold.

The Knowledge Wiki pattern avoids the 'reading tax' of re-reading a document corpus for every agent query by consolidating a corpus into a single, structured memory store once.

The Pipeline Steps

1. Assemble Corpus: Gather documents (data rooms, discovery sets, etc.).
2. Normalize: Convert all file types (PDF, Word, etc.) to plain text with a [SOURCE: …] header for provenance.
3. Parallel Extraction: Split the corpus into batches. Run concurrent agent sessions that write structured notes into a shared memory store (the wiki). Each source document should have its own single-writer path to prevent overwrites.
4. Resolve Open Questions: A cross-reading pass to close gaps left by extraction. Mark missing info as confirmed-unresolvable instead of guessing.
5. Consolidate (Dreaming): A server-side 'sleep-time' compute pass that reads transcripts and the store to write a new, reorganized store with deduplicated entities, an index, and repaired links. This step uses the POST /v1/dreams endpoint.
6. Query: Attach the consolidated store read-only to fresh agent sessions. Require provenance for every fact and script specific 'miss' behavior (e.g., naming the missing document).
7. Operate: Periodically run 'dreaming' over real usage transcripts to reorganize the wiki around actual user queries.
8. Evaluate: Grade outputs against a rubric to tune extraction rules and prompts.