After studying this material, you should be able to:

1. Explain what the Agent SDK is and what problem it solves
2. Describe the core components that make up an Agent SDK agent
3. Identify key features of the Agent SDK
4. Understand how to deploy and manage agents
5. Apply basic setup knowledge to start building an agent

---

Step-by-Step Study Material

Step 1: Understanding the Problem Being Solved

Why does Agent SDK exist?

Software teams repeatedly handle the same tasks across their development lifecycle:

• Reviewing pull requests
• Running compliance checks
• Investigating incidents

Before Agent SDK, teams had two painful options:

Agent SDK solves this by giving teams a framework to build custom agents that match their specific workflow.

💡 Key Insight: The same framework Cursor uses internally for Bugbot, Security Reviewer, and Rollouts is now publicly available.

---

Step 2: Understanding What an Agent Actually Does

An agent is essentially a automated worker that:

Trigger Event → Agent Responds → Takes Action → Produces Outcome

Real-World Example: kb-reviewer

A Cursor team needed every pull request checked against their knowledge base of lessons learned.

The workflow:

1. Developer opens a Pull Request
2. Agent detects the PR event
3. Agent checks changes against the knowledge base
4. Agent flags contradictions and cites relevant notes
5. Engineer reviews and reconciles discrepancies

Result: Built in approximately one day, now runs on every PR automatically.

---

Step 3: Core Components of an Agent SDK Agent

Think of an agent as a small software project with specific files:

my-agent/
├── prompts/          ← Instructions written in Markdown
├── tools/            ← Capabilities written as TypeScript functions
├── integrations/     ← Connections to outside services (GitHub, GitLab, etc.)
└── evals/            ← Tests to verify agent behavior

Breaking Down Each Component

Prompts (Markdown files)

• Written in plain Markdown
• Define how the agent thinks and behaves
• Can be reviewed and changed like any document

Tools (TypeScript functions)

• Define what the agent can do
• Example: fetch a PR, post a comment, check a database

Integrations

• Connect to services your team already uses
• Supported platforms: GitHub, GitLab, Bitbucket

Evals

• Tests that verify the agent behaves as expected
• Allow rapid iteration without breaking critical workflows

💡 Key Insight: Because everything is code, agents go through the same version control and review process as your regular software.

---

Step 4: Key Features to Know

Feature 1: Event-Driven Responses

Agents respond to events your team already handles:

• Pull request opened
• Incident triggered
• Compliance check needed

Feature 2: Multi-Agent Collaboration

For complex work, agents can:

Main Agent
    ├── Hand off task → Specialized Sub-Agent (with own tools)
    └── Divide work  → Multiple Parallel Sub-Agents

Feature 3: Built-in Evals and Event Replay

• Test agents before deploying
• Replay past events to verify behavior
• Enables fast iteration with confidence

Feature 4: Flexible Deployment

---

Step 5: Understanding Deployment

Deploying to Cursor Infrastructure

agent-sdk deploy

This single command:

1. ✅ Builds the agent
2. ✅ Assigns it a URL
3. ✅ Starts it on Cursor's infrastructure

After deployment, manage via dashboard:

• Secrets
• Integrations
• Logs
• Evals
• Playground

Running on Your Own Infrastructure

• Each agent runs as a single Node.js process
• Can be packaged in a container
• Full control over your environment

---

Step 6: Getting Started — Basic Code Structure

Here is the minimal code to define an agent:

import { homedir } from "node:os";
import { join } from "node:path";
import { defineAgent } from "@cursor/agent-sdk";

export default defineAgent({
  name: "Robo",                    // Agent's name
  model: {
    id: "composer-2.5",            // Which AI model to use
    params: [
      { id: "effort", value: "high" },   // Quality setting
      { id: "fast", value: "true" },     // Speed setting
    ],
  },
  local: {
    cwd: join(homedir(), ".cache", "factory", "robo"),  // Local working directory
  },
})

Breaking Down the Code

Development Workflow

1. Create project directory
        ↓
2. Launch local playground
        ↓
3. Iterate and test locally
        ↓
4. Run evals to verify behavior
        ↓
5. Deploy with: agent-sdk deploy

---

Summary: The Big Picture

PROBLEM                    SOLUTION
─────────────────────────────────────────────────────
Repetitive dev tasks   →   Define agents as code
Rigid existing tools   →   Build around YOUR workflow
Hard to test           →   Built-in evals + event replay
Complex deployment     →   One command: agent-sdk deploy
Scaling complexity     →   Multi-agent collaboration

Three Things to Remember

1. Agents are code — version controlled, reviewable, changeable
2. Agents are event-driven — they respond to things that already happen in your workflow
3. Agents are flexible — deploy to Cursor or your own infrastructure

---

Quick Knowledge Check

Ask yourself:

• Can I explain what problem Agent SDK solves?
• Can I name the four components of an agent project?
• Can I describe the deployment process?
• Can I read the basic defineAgent code and explain each part?
• Can I explain what evals are used for?

If you can answer all five, you have successfully understood the core concepts of the Agent SDK.