Building AI Agents with the Cursor Agent SDK

Engineering Reference for Production-Grade Agentic Systems

Introduction

Chapter 1: What the Cursor Agent SDK Is and Is Not

1. The Cursor Platform Landscape
2. SDK vs Agent SDK vs CLI
3. The Agent-as-Code Paradigm
4. What Problems the Agent SDK Solves
5. What It Does Not Solve

Chapter 2: Installation, Configuration and Environment

1. Node.js and Runtime Requirements
2. Installing the CLI and SDK
3. Authentication and API Keys
4. Project Initialization and Templates
5. Directory Structure Deep Dive
6. Configuration Sources and Precedence

Chapter 3: The Agent Project Anatomy

1. The defineAgent Contract
2. Instructions and Prompt Design
3. The Tools Directory
4. Skills and On-Demand Procedures
5. MCP Connections
6. Channels and Triggers
7. Hooks and Extensions

Chapter 4: Agent Lifecycle and Execution Model

1. Session and Turn Semantics
2. The Model Loop
3. Execution Phases and State Transitions
4. Streaming Events and Trajectories
5. Request IDs and Observability
6. Error States and Recovery

Chapter 5: Prompting and Instruction Design

1. The Role of instructions.md
2. Prompt Structure and Clarity
3. Constraint-Based Prompting
4. Multi-Modal Instructions
5. Testing and Iterating Prompts
6. Common Anti-Patterns

Chapter 6: Tool Design and Implementation

1. What a Tool Is in the Agent SDK
2. Tool Signature and Schema Design
3. Parameter Validation
4. Return Value Patterns
5. Idempotency and Safety
6. Tool Discovery and Selection

Chapter 7: Model Context Protocol Integration

1. MCP in the Agent SDK Ecosystem
2. Configuring MCP Connections
3. stdio vs HTTP/SSE Transport
4. Authentication Patterns
5. Tool and Resource Exposure
6. Security Considerations

Chapter 8: Channels and Event Triggers

1. Channel Architecture
2. GitHub and GitLab Triggers
3. Slack and Messaging Channels
4. Webhook Channels
5. Scheduled and Cron Triggers
6. Session Continuity and Context

Chapter 9: Subagents and Delegation

1. The Subagent Model
2. Defining Subagents
3. The Task Tool and Delegation
4. Nesting Rules and Depth Limits
5. Context Isolation
6. Error Propagation

Chapter 10: The Cursor SDK for Programmatic Control

1. SDK Architecture and Runtimes
2. Agent.create and Configuration
3. Local vs Cloud vs Self-Hosted Runtimes
4. Sending Messages and Runs
5. Streaming and Event Handling
6. Custom Tools via SDK

Chapter 11: State Management and Persistence

1. Conversation State Model
2. Agent.resume and Session Restoration
3. Store Implementations
4. Custom Store Design
5. State Lifecycle and Cleanup

Chapter 12: External Service Integration

1. Secrets Management
2. Environment Variables
3. API Client Patterns
4. Connection Management
5. Egress Control
6. Failure Handling

Chapter 13: Evals and Automated Testing

1. The Eval Framework
2. Writing Evals
3. Asserting Tool Execution
4. Output Shape Validation
5. CI/CD Integration
6. Regression Testing

Chapter 14: Observability and Debugging

1. Session Inspection
2. Log Aggregation
3. Trace Files and Trajectories
4. Metrics and Cost Tracking
5. Debugging Failed Runs
6. Production Debugging Patterns

Chapter 15: Error Handling, Retries and Resilience

1. Error Categories and Sources
2. CursorSdkError Hierarchy
3. Rate Limiting and Backoff
4. Timeouts and Cancellation
5. Partial Failure and Rollback
6. Circuit Breaker Patterns

Chapter 16: Security and Threat Modeling

1. The Agent Threat Model
2. Prompt Injection Risks
3. Sandbox Escapes and CVE History
4. Tool Permission Design
5. Network and Egress Security
6. Secrets Protection

Chapter 17: Deployment Architecture

1. Managed Hosting Workflow
2. Self-Hosting Requirements
3. Container Deployment
4. Multi-Agent Serving
5. TLS and Auth Proxy
6. Health Checks

Chapter 18: Configuration Management and Secrets

1. Secret Declaration and Injection
2. Environment-Specific Config
3. Egress Domain Policies
4. Team-Level Controls
5. Secret Rotation
6. Audit Logging

Chapter 19: Performance, Cost and Scaling

1. Token Budgeting
2. Model Selection and Router
3. Run-Time Optimization
4. Concurrent Execution
5. Cost Monitoring
6. Scaling Strategies

Chapter 20: Advanced Architectural Patterns

1. Coordinator-Worker Patterns
2. Event-Driven Ambient Agents
3. Embedded Product Agents
4. Human-in-the-Loop Workflows
5. Multi-Step Approval Chains
6. Cross-Agent Communication

Chapter 21: CLI and Tooling Reference

1. Development Commands
2. Deployment Commands
3. Session and Debugging Commands
4. Eval Commands
5. Secret Management Commands
6. Exit Codes and Diagnostics

Chapter 22: Production Readiness Checklist

1. Security Checklist
2. Reliability Requirements
3. Observability Requirements
4. Testing Requirements
5. Operational Runbook Essentials
6. Common Failure Modes

References