AI Agent Development Framework in Practice: Building Your Intelligent Dev Assistant

After reading this tutorial, you will master how to configure and use AI agent development tools to complete real coding tasks. I will use a real AI agent development framework as an example, walking through everything from environment setup to completing a full feature. You will learn how to make an AI agent understand your codebase, autonomously plan development steps, generate high-quality code, and handle various problems encountered during development.

Whether you are using Cursor, Windsurf, or other similar AI agent tools, this methodology is universal. Ready? Let's get started.

1. What You Will Learn

After completing this tutorial, you will be able to:

• Configure an AI agent development environment: From installation to API key setup to project association — the full pipeline
• Make the agent understand your codebase: Through context and rule files, let the AI agent "read" your project
• Complete a full feature development: From requirement description to code generation to verification testing — the complete walkthrough
• Troubleshoot and solve common problems: How to handle agent non-responses, code going off-track, context overflow, etc.
• Advanced usage techniques: Custom rules, multi-round iteration, plan review — advanced practical applications

2. Prerequisites

Before starting, you should have a basic understanding of these concepts. No worries if not — just get familiar with them first:

• Command line basics: Knowing how to switch directories and run commands in a terminal
• Git basics: Understanding commits and branches, knowing what .gitignore does
• At least one programming language: Whether you write Python, JavaScript, or Go — having a primary language helps you learn faster
• API key concept: Knowing this is a "passport" that shouldn't be casually shared

If you are completely unfamiliar with these, I recommend spending half an hour on the basics first — but mastery is not required. You will naturally become familiar through this tutorial.

3. Environment Setup

Get the tools ready first. I will use Cursor as the primary example (since it is currently the most popular AI agent IDE), but the approach applies to other similar tools.

• Cursor latest version: An AI agent development IDE with integrated Composer and other advanced features. Download from https://cursor.sh/download, install, and register an account
• Node.js 18+: If your project is JavaScript/TypeScript, you need this. Run node -v to verify the version
• Git: Version control tool — AI agents need it to understand code change history. Run git --version to verify installation
• Code editor basic configuration: Recommended to install common VS Code extensions (skip this if using Cursor as your primary IDE)

After installing Cursor, you need to associate an API. Cursor supports multiple models — select the one you need under Settings → Models and enter your API Key. If you have OpenAI or Anthropic accounts, enter the corresponding keys directly. New users can start with free trial credits.

For this tutorial, I assume you are using Cursor's built-in Composer feature, which is currently one of the most mature AI agent development interfaces. If you are using another tool like Windsurf, the logic is similar — find the corresponding "Composer" or "Agent" feature entry.

4. Core Concepts

Before discussing specific steps, let's talk about the difference between AI agents and ordinary code completion tools. This is important.

Ordinary code completion (like basic GitHub Copilot) is a "single question-answer" mode — you write a line, it completes the next line. Good for small edits, checking syntax, translating comments. But for requests like "refactor this module for me," it falls short.

AI agents are different. They use an "autonomous planning + multi-round execution" mode. You tell them the goal, and they will:

1. Analyze the current state: Scan your codebase to understand project structure and tech stack
2. Make a plan: Break it into multiple subtasks — e.g., "first look at the database model, then change the API interface, finally write tests"
3. Execute step by step: Complete tasks one at a time, giving you feedback at each step
4. Verify results: Run tests to check if the logic is correct

It is like having a junior engineer working next to you — you direct, they execute, and they check in with questions when they encounter problems.

Cursor's Composer is this "interface." You can input natural language descriptions in the right-side panel, and it calls an AI model as an agent to understand and operate on your code. Composer can read and write files, execute commands, search code, run tests — basically covering the full development workflow.

Another key concept is Context. How much code an AI agent can "see" determines its output quality. If you only show it one file, it can only work within that file. If you let it scan the entire project, it can understand inter-module dependencies and do global refactoring or feature expansion. So configuring context properly is the first hurdle to using AI agents well.

5. Practical Steps (Part 1)

Concepts covered — time to get hands-on.

1. Initialize a project and connect to Cursor

Find a project you are familiar with, or create a new test project. I will use an Express.js REST API project as an example.

mkdir test-agent-project && cd test-agent-project
npm init -y
npm install express cors dotenv
npm install -D nodemon
git init
echo "node_modules/" >> .gitignore
echo ".env" >> .gitignore

Then open this directory in Cursor:

cursor .

In Cursor, open app.js and write some basic code:

const express = require('express');
const cors = require('cors');
require('dotenv').config();

const app = express();
app.use(cors());
app.use(express.json());

app.get('/', (req, res) => {
  res.json({ message: 'Hello World' });
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

Your project is now ready.

2. Open Composer and have your first conversation

In Cursor, press Cmd/Ctrl + I to open the Composer panel (some versions use Cmd/Ctrl + K then select Composer). You will see an input box.

Enter the following:

Analyze this project's structure and tell me what tech stack it uses and the main functions of key files.

Press Enter to send.

The agent will start working — you will see its thinking process and execution logs on the right. It will scan project files, read package.json, identify the tech stack, and give you a summary.

Expected output similar to:

I analyzed your project — it is an Express.js REST API project.

Tech stack:
- Express.js: web framework
- cors: cross-origin resource sharing
- dotenv: environment variable management
- nodemon: hot reload during development

Main files:
- app.js: application entry point, configured middleware and routes
- .gitignore: ignores node_modules and other files not needing version control

The project structure is relatively simple, currently only one main file.

If the agent does not respond, first check if the API Key is configured correctly (Settings → Models → API Key). If you get a "context too long" error, see the optimization section below.

3. Let the agent add a new feature

Now let the agent actually write some code. Let's add a user list GET endpoint to this API.

In Composer, enter:

Add a GET /users endpoint in app.js that returns a JSON array of 3 sample users.
User objects should include id, name, and email fields.

The agent will analyze the existing code, find the right place to insert the new route, generate the code, and show it to you.

Expected output similar to:

I will add the /users route in app.js.

Changes:
```javascript
// Add after app.get('/')
app.get('/users', (req, res) => {
  const users = [
    { id: 1, name: 'Alice', email: 'alice@example.com' },
    { id: 2, name: 'Bob', email: 'bob@example.com' },
    { id: 3, name: 'Charlie', email: 'charlie@example.com' }
  ];
  res.json(users);
});

Accept this change? [Accept] [Reject] [Modify]

Click "Accept" and the code is written to the file.

## 6. Practical Steps (Part 2)

### 4. Let the agent create a new module

Adding a route is not enough — let's do something more complex. Create a standalone user module and separate user-related logic.

In Composer, enter:

Create a users.js file as a user module containing:

1. A getUsers() function that returns the user array
2. A getUserById(id) function that returns a single user by ID, or null if not found
3. A createUser(data) function that receives user data and returns the created user object (with auto-generated ID)
4. Export these three functions

Then modify app.js to import this module and have the /users route use the module's functions.

The agent will create a new file, write the function logic, and modify the imports and routes in app.js.

**Expected output:**

I made the following changes:

1. Created users.js:

let users = [
  { id: 1, name: 'Alice', email: 'alice@example.com' },
  { id: 2, name: 'Bob', email: 'bob@example.com' },
  { id: 3, name: 'Charlie', email: 'charlie@example.com' }
];

function getUsers() {
  return users;
}

function getUserById(id) {
  return users.find(user => user.id === id) || null;
}

function createUser(data) {
  const newUser = {
    id: users.length > 0 ? Math.max(...users.map(u => u.id)) + 1 : 1,
    ...data
  };
  users.push(newUser);
  return newUser;
}

module.exports = { getUsers, getUserById, createUser };

2. Modified app.js, added routes:

const { getUsers, getUserById } = require('./users');

// GET /users - get all users
app.get('/users', (req, res) => {
  res.json(getUsers());
});

// GET /users/:id - get single user
app.get('/users/:id', (req, res) => {
  const user = getUserById(parseInt(req.params.id));
  if (user) {
    res.json(user);
  } else {
    res.status(404).json({ error: 'User not found' });
  }
});

Accept these changes?

Accept the changes, then start the service with `npm run dev` and test if the endpoints work.

### 5. Let the agent add input validation

Features are there, but not robust enough. Let the agent add validation:

Add input validation to the POST /users endpoint:

1. name is required, minimum 2 characters
2. email is required, must be a valid email format
3. If validation fails, return 400 status with specific error messages

The agent will modify users.js or app.js to add validation logic.

### 6. Let the agent generate test files

Code is written — time to write tests:

Generate test file test/users.test.js for the users module
Test cases should cover:

1. getUsers() returns an array
2. getUserById() can find an existing user
3. getUserById() returns null for non-existent ID
4. createUser() can create a new user
5. createUser() throws error when required fields are missing

The agent will create the test file. Run the tests to verify:

```bash
npm install -D jest
npx jest test/users.test.js

Expected output similar to:

PASS  test/users.test.js
  ✓ getUsers() returns an array
  ✓ getUserById() can find an existing user
  ✓ getUserById() returns null for non-existent ID
  ✓ createUser() can create a new user
  ✓ createUser() throws error when required fields are missing

Test Suites: 1 passed, 1 total
Tests:       5 passed, 5 total

7. Key Code/Configuration Deep Dive

This section dives deeper into Cursor's configuration files. Understanding these will help you use it more smoothly.

Composer Configuration

Cursor's settings file is at ~/.cursor/settings.json (global) or .cursor/settings.json in the project root (project-level). Key configurations:

{
  "cursor.composer.maxTokens": 8192,
  "cursor.composer.temperature": 0.7,
  "cursor.composer.contextMode": "project"
}

• maxTokens: Maximum length per reply. Default 8192 is fine for small features, but if the agent needs to write a lot of code (like a whole module), consider raising to 16384 or higher. Otherwise, output gets cut off mid-way and you have to manually continue.
• temperature: Controls output "randomness." Between 0 and 1 — lower is more conservative and stable, higher is more creative. For coding tasks, 0.5-0.7 is suitable. Too low may produce repetitive results; too high may produce wild code.
• contextMode: Context scope. file only looks at the current file, open looks at all open tabs, project scans the entire project. For tasks requiring global understanding, use project.

.cursorrules Project Rules

This is an interesting file. You can create a .cursorrules file in the project root with project-specific coding standards, and the agent will automatically follow them.

For example:

# Project Rules

## Code Style
- Use 2-space indentation
- Use single quotes for strings
- No semicolons at line end

## API Design
- RESTful style
- Error response format: { error: "description" }
- Success response format: { data: {...} }

## Testing Requirements
- Every module must have a test file
- Test files go in test/ directory
- Use Jest framework

With this file, code generated by the agent automatically conforms to your project standards without needing to remind it every time.

.cursorignore to Exclude Irrelevant Files

Similar to .gitignore, you can specify in .cursorignore which files or directories the agent should not scan:

node_modules/
dist/
*.log
.env
coverage/

This prevents the agent from wasting time on irrelevant files and keeps the context cleaner.

8. Effect Verification

How to confirm your configuration is correct and the agent is working properly? Use this verification flow:

8.1 Verify the agent can read the project

In Composer, enter:

List all files and directories in the project root.

If it returns the correct file list, the agent can access your project. If it returns empty or errors, check that you properly opened the project directory in Cursor.

8.2 Verify the agent can write files

Have the agent create a test file:

Create a temp-test.txt file in the project root with the content "test"

Then check whether the file was actually created. If it doesn't exist, the agent's write permissions may be restricted (some settings disable write functionality).

8.3 Verify the agent can execute commands

In Composer, enter:

Run node -v and tell me the result

The agent should be able to run the command and return the output. If you get a permission error, check if terminal execution is enabled in Cursor's settings.

8.4 Verify the complete feature development flow

Follow the steps in sections 5 and 6 to complete a feature addition and testing. If you can smoothly go from requirement description through code generation to passing tests, your environment is fully ready.

9. FAQ and Troubleshooting

After using AI agents for a few days, here are the most common pitfalls:

• Problem: Agent says "context too long, cannot process"
  Cause: Too many project files, or a single file too large, exceeding the model's processing capability. Fix: Create or update .cursorignore to exclude irrelevant content like node_modules, dist, log files, etc. Or split large files into smaller modules. If still over the limit, use contextMode: "file" to only let the agent see the current file.

• Problem: Agent-generated code style is inconsistent with existing code
  Cause: No project rules configured, or the agent didn't notice the existing code style. Fix: Create .cursorrules file defining code style. Explicitly say "reference the existing code style" in the conversation. Manually adjust the agent's output, then tell the agent "use this code as a template" for rewriting.

• Problem: Agent "goes off track" — generated code is not what I wanted
  Cause: Requirement description was not clear enough, or the agent misunderstood. Fix: Break the task into smaller steps. Explicitly state "don't do X" rather than only "do Y." Use "stop" or "restart" to reset the agent's context, then describe the requirement more clearly.

• Problem: Agent doesn't read the latest modified code
  Cause: The agent's context is a snapshot from a point in time — it can't see later modifications. Fix: Say "re-analyze project" or "refresh context" in Composer. Ensure modified files are saved (Cmd/Ctrl + S). Close and reopen the Composer panel.

• Problem: Tests fail but agent says the code is correct
  Cause: The agent's judgment is not always accurate — it doesn't actually have a runtime environment. Fix: Manually run tests to see specific errors. Paste error messages to the agent and let it fix based on actual errors. Debug step by step instead of having the agent write large amounts of code at once.

• Problem: Agent-generated code has security vulnerabilities
  Cause: AI models don't always know the latest security best practices. Fix: Review agent-generated code yourself, especially parts involving user input and database operations. Add extra validation and protection for sensitive operations. Add security requirements in .cursorrules, e.g., "all user input must be validated and sanitized."

10. Advanced Directions

After learning the basics, you can explore these advanced directions:

Custom Project Rule System

Beyond code style, you can write architectural decisions into .cursorrules. For example: "All data access must use the Repository pattern," "Database connections must use connection pools," "API response time must not exceed 200ms." The agent will understand and follow these constraints, working within your architectural framework rather than making wild decisions.

Multi-round Iteration Optimization

Don't expect the agent to write perfect code on the first try. Treat its output as a first draft, then iterate and optimize through multiple rounds of conversation. For example: "Can this logic be more concise?" "Add error handling." "Rewrite with arrow functions." "Add JSDoc comments." Each iteration improves on the last — this is the normal pattern for collaborating with agents.

Plan Review Mode

For large tasks, have the agent output an execution plan first and wait for your confirmation before executing. In Composer, say: "First tell me what you plan to do — don't write code yet." The agent will list the steps. You review and say "OK, start executing" before it actually acts. This avoids wasted effort — sometimes the agent's plan has problems you can spot at a glance.

Integration into CI/CD Pipeline

Agent-generated code can also enter your automation process. Configure CI to run tests and lint on every PR. If the agent's output has issues, automated tests will catch them. This is not about "the agent having problems" — it is about having a safety net. Whether code is written by a human or an agent, it must pass the same checks.

---

That brings this tutorial to an end. You have learned the basics of AI agent development tools, from environment configuration to completing a full feature to troubleshooting and advanced techniques.

The three things to remember: describe requirements clearly, break tasks into small steps, and continuously verify results. AI agents are not silver bullets. They are more like a very diligent intern who needs clear guidance — you must tell them what to do and how to do it to get the results you want.

If you are using tools other than Cursor, the approach is the same: find the corresponding Agent/Composer feature entry, describe requirements the same way, and adjust prompts based on output. Tools change; methodology is universal.

Go try it out. When you have questions, come back to this tutorial anytime.