A Software Delivery Playbook for Building, Evaluating, and Deploying Agent SDK Agents

Software delivery teams rarely need generic automation; they need behavior that fits the repository, the review chain, the incident channel, and the rules the team already has written down. Today, the Agent SDK gives engineering teams a code-first way to build that behavior. It is the framework used to build managed agents such as Bugbot, Security Reviewer, and Rollouts, and it lets teams define an agent the way they define any other software component: in files, under version control, and with tests.

That distinction matters in delivery practice. An agent needs to listen where the team already works and react when relevant events happen, including pull-request checks, compliance workflows, and incident investigation. Instead of forcing the team into a process shaped for another environment, the agent can encode the team's own standards. When it is ready, agent-sdk deploy sends it to Cursor infrastructure with one command.

Why Code-Defined Agents Matter for Development Teams

The earlier trade-off was simple: use a product configured for another organization's workflow, or build everything yourself. The Agent SDK changes that by making the agent a software project. Teams can begin from a template or from documentation aimed at a coding agent, then adapt the agent to the rules already captured in the repository.

For engineering leaders, the operational consequence is clearer than the marketing consequence. Agents can be reviewed like code, changed like code, and connected to real sources of engineering signal. Pull-request events can arrive from GitHub, GitLab, or Bitbucket. Inside the agent, those signals can be judged against the team's own standards, routed to the right group, and used to approve or flag a change when policy allows.

An agent becomes useful when it reflects a particular team's conventions. That determines how prompts are written, which tools are exposed, which events are trusted, and how success is measured before deployment.

Building One Agent Around a Real Pull-Request Workflow

Code review is a natural first place to apply the pattern. Every team has its own expectations for what needs attention, what risk level requires escalation, and which reviewers should see a change. An Agent SDK agent can react to pull-request events, assess risk, route work to the appropriate team, and approve changes that meet policy.

Inside Cursor, one team illustrates the pattern. The team had built a fast-growing knowledge base of lessons learned and wanted every pull request checked against it, so past decisions would hold even as the codebase changed. They created kb-reviewer in about a day. The agent now checks every PR in the team's main codebase. When a change conflicts with a lesson already recorded, it identifies the finding, points to the supporting note, and asks engineers to reconcile the difference.

That example is useful because it turns a known source of review drift into an automated check. The agent does not invent a new workflow; it reads the workflow the team already captured. For software development managers, this suggests a good first agent target: a recurring engineering task with explicit rules, visible triggers, and outcomes that can be reviewed.

Describing Agent Components in Code

An Agent SDK agent is organized like a small software project. Guiding instructions, tool code, connections to outside services, and evals live together in the project.

Files encode what the agent knows and what it can do: Markdown holds prompts, while TypeScript functions define tools. Because the agent is code, changes can follow the same version control and review process used for the rest of the software project.

For teams, that means an agent should be treated as a maintained internal service, not a one-off configuration screen. If the policy changes, the instruction file changes. If the team adds a new integration, the connection code changes. If a review rule needs proof before release, the eval suite changes.

More involved work can be split. One agent may pass a task to a specialized agent that has its own tools and sessions; another pattern is to divide a job among subagents running in parallel. That matters when a single pull request may need security reasoning, knowledge-base comparison, compliance evidence, and routing logic handled as separate concerns.

Evals and Event Replay: Making Safe Iteration Practical

Agent behavior can be difficult to reason about when it is described only in prose. Out-of-the-box evals and event replay are part of the framework. They let teams develop quickly while keeping confidence that important workflows behave correctly. For software teams, event replay is especially relevant because the signals are often historical: a pull request, a policy conflict, an incident signal, or a sequence of tool calls.

PGA Tour uses the Agent SDK to power its software development factory, and evals keep that team moving quickly.

The Agent SDK has enabled PGA to build every component of our software factory on Cursor's infrastructure. It provides the flexibility we need to build agents that drive our development process. And built-in support for evals allows us to quickly iterate on new ideas and optimize existing capabilities reliably.

Michael Gyarmathy, Principal Engineer, PGA America

The practical lesson is that speed is not only about shipping an agent; it is about knowing whether a change made the agent better or worse. Evals give a team a way to compare behavior before the agent is placed in front of real engineering events.

Deployment Choices: Cursor Infrastructure or Self-Managed Runtime

Running agent-sdk deploy in the project directory packages the agent, assigns a URL, and launches it on Cursor infrastructure. The dashboard can manage secrets and integrations, while the local environment keeps the same logs, evals, and playground.

An agent can also stay inside a team's own infrastructure. It can run as a single Node process, and that process can be packaged in a container.

Teams should choose between these deployment paths using the same questions they use for any internal service: where should the runtime live, who manages secrets, how are logs retained, how are integrations controlled, and how can developers reproduce behavior locally? The table below summarizes the deployment surface described by the Agent SDK.

Deployment path	How it starts	Runtime location	Operations surface	Engineering implication
Managed Cursor deployment	agent-sdk deploy sends the agent to Cursor infrastructure with one command.	Cursor infrastructure.	Secrets and integrations can be managed from the dashboard; logs, evals, and playground remain available locally.	Good for teams that want a short path from a code-defined agent to a running agent.
Self-managed runtime	The same project can be run as a single Node process packaged in a container.	Your own infrastructure.	Operational responsibility remains with the team, while the agent code and local evaluation surface stay available.	Useful when an organization needs placement inside its own runtime environment.

Step-by-Step: Building a Starter Agent in the Local Playground

Starting work is like starting a normal software project. First, create a project directory and launch the local playground.

1. Create a project directory.
2. Launch the local playground.
3. Define a starter agent. In one starter example, the agent may import homedir from node:os and join from node:path, then call defineAgent from @cursor/agent-sdk. The sample can use the name Robo, the model composer-2.5, params effort high and fast true, and a local cwd based on homedir: .cache/factory/robo.
4. Iterate locally and run evals before shipping.
5. Deploy with agent-sdk deploy when the behavior is acceptable.
6. Use the skills shipped with the Agent SDK to guide a coding agent through the development process, so an agent can point at the docs and help build the bot.

The sequence is intentionally close to normal engineering work: create the project, make the behavior visible, test it, then deploy. The local playground is the point where a team can examine prompts, tool wiring, and evaluation results before the agent becomes a running process.

Common Pitfalls and Practical Guardrails

The following pitfalls are common when teams automate software-development workflows, and they can be addressed with the structure the Agent SDK already exposes.

• Choosing an agent before choosing a workflow. The most useful agents attach to events the team already handles. If the workflow is unclear, the agent will inherit that ambiguity.
• Copying another team's process. If the goal is an agent that behaves like your team, define the policy in code and review it alongside the rest of the project.
• Shipping without evals. The Agent SDK includes evals and event replay for a reason: critical workflows need assurance before they operate on real changes, reviews, incidents, or compliance checks.
• Treating knowledge-base checks as optional. The kb-reviewer example shows how recorded lessons can keep pull-request decisions stable even as a codebase changes.
• Ignoring the split between local and deployed behavior. Keeping logs, evals, and the playground available locally helps teams reproduce what they observe in Cursor or in a self-managed runtime.

FAQ for Software Development Teams

What can teams build with the Agent SDK?

The Agent SDK is used to build managed agents such as Bugbot, Security Reviewer, and Rollouts. It also lets a team define its own agent in code, then manage it like any other software project.

Where do these agents get their work?

Agents can respond to events the team already handles. Pull-request checks, compliance workflows, and incident investigation are examples. Events can arrive from GitHub, GitLab, or Bitbucket.

Can the agent enforce team policy?

Yes, if policy is encoded in the agent. An agent can judge the risk of a change, route it to the right team, and approve changes that meet policy. Because prompts and tools are code, the policy can be inspected and changed.

Do agents need to run on Cursor infrastructure?

No. Teams can use agent-sdk deploy to send an agent to Cursor infrastructure with one command, or run the agent on their own infrastructure as a single Node process that can be packaged in a container.

How can teams make changes safely?

Use evals and event replay. They are included out of the box and support rapid iteration while giving teams assurance that critical workflows execute as expected.

What is the first practical step?

Create a project directory, launch the local playground, and start from a template or documentation aimed at a coding agent. A starter agent can use defineAgent from @cursor/agent-sdk and set parameters such as name Robo and model composer-2.5 before being tested locally.

Action Recommendations for Engineering Teams

Software teams can turn the Agent SDK release into a practical delivery checklist by selecting a bounded workflow and implementing it as a versioned project.

• Start with one recurring event stream, such as pull requests from GitHub, GitLab, or Bitbucket.
• Define the expected behavior as Markdown prompts and TypeScript tools, then keep them under the same review process as application code.
• Add evals for the decisions that matter: risk judgment, routing, approval, and any check against recorded lessons.
• Pilot an agent similar to kb-reviewer before expanding to incident or compliance workflows.
• Choose the deployment path deliberately: managed Cursor infrastructure with agent-sdk deploy and one command, or a self-managed single Node process in a container.
• Replay events when behavior changes, especially when the team updates policy, tools, or integrations.

For teams working on software delivery, the important change is not that an agent can exist; it is that the agent can be written, reviewed, tested, and operated with the same discipline as the rest of the system. The Agent SDK is generally available today, and teams can read the docs and get started.