Lab 3: Agents in Action

​

How agents think and work

1. Understands what you’re asking for
2. Explores your codebase to gather context
3. Plans how to solve the problem
4. Executes the changes (writing code, running commands)
5. Verifies the work (running tests, checking output)

​

Agent capabilities

• Read and write files - View code, create new files, edit existing ones
• Execute commands - Run builds, tests, linters, deployment scripts
• Search codebases - Find functions, classes, patterns across your code
• Open pull requests - Create branches, commit changes, push to remote
• Use bash commands - Run !git status, !npm test for quick context
• Respond to feedback - Iterate based on your guidance

​

Talking to your agent

​

Practical scenario 1: Add error handling

​

The prompt

Look at the POST /api/transactions endpoint in backend/server.js.
Add input validation before processing the transaction:
- Validate that portfolio_id and stock_id are provided
- Validate that quantity is a positive number
- Validate that price_per_share is a positive number
- Validate that transaction_type is either "BUY" or "SELL"
- Return 400 with a descriptive error message for invalid inputs
- Follow the error handling pattern already used in the SELL branch

​

What the agent does

1. Explores: Reads backend/server.js to understand the existing transaction endpoint and error patterns
2. Plans: “I’ll add validation checks at the top of the handler, before the transaction logic runs”
3. Executes: Adds validation code with appropriate 400 responses
4. Verifies: Tests the endpoint with curl to confirm valid and invalid requests behave correctly

​

Why this works

• Specific: You named the exact file and endpoint
• Examples: You referenced an existing pattern in the same file
• Clear outcomes: You listed the specific validations to add

​

Practical scenario 2: Write tests

​

The prompt

The backend API in backend/server.js has no tests.
Create a test file backend/server.test.js using the built-in Node.js test runner.

Cover these cases for POST /api/transactions:
- Successful BUY transaction
- Successful SELL transaction
- SELL with insufficient shares returns 400
- Missing required fields

Also test GET /api/portfolios/:id:
- Valid portfolio returns holdings
- Non-existent portfolio returns 404

Run the tests to make sure they pass.

​

What the agent does

1. Reads backend/server.js to understand the API routes and data flow
2. Checks backend/package.json for available test tooling
3. Writes test cases covering the specified scenarios
4. Runs the tests to verify they pass
5. Shows you the test results

​

Why this works

• Specific file and endpoints named
• Test framework specified
• Test cases enumerated
• Verification requested (run tests)

​

Practical scenario 3: Add a new feature

​

The prompt

The app can display portfolios but there's no way to create one from the UI.

1. Add a POST /api/portfolios endpoint in backend/server.js that accepts
   a JSON body with "name" and "description" fields. Validate that "name"
   is provided. Return 400 if missing.

2. Add a simple form component in frontend/src/components/CreatePortfolioForm.jsx
   that lets users type a name and description, then submits to the new endpoint.
   Follow the style of TransactionForm.jsx.

3. Wire the new form into frontend/src/App.jsx.

Test the endpoint with curl, then verify the form works in the browser.

​

What the agent does

1. Reads backend/server.js and frontend/src/components/TransactionForm.jsx to understand existing patterns
2. Adds the new API endpoint with validation
3. Creates the form component matching the existing style
4. Updates App.jsx to include the new form
5. Tests with curl and checks the frontend renders correctly

​

Why this works

• Named the problem: No way to create portfolios from the UI
• Suggested structure: Listed the backend and frontend changes separately
• Referenced existing patterns: “Follow the style of TransactionForm.jsx”
• Verification: “Test with curl, then verify the form”

​

Using bash commands for context

!git status
!npm test
!ls src/components
!grep -r "TODO" src/

​

Example workflow

​

Writing effective prompts

​

Pattern 1: The explorer

Find all places where we make API calls to the /users endpoint.
List the files and what each call does.

​

Pattern 2: The planner

I want to add a "remember me" checkbox to the login form.
First, create a plan showing:
1. What files need to change
2. How you'll store the preference
3. How you'll extend the session duration

Show me the plan before implementing.

​

Pattern 3: The validator

Review the changes I just made to auth.ts.
Check for:
- Security issues (XSS, injection, etc.)
- Edge cases I might have missed
- Opportunities to simplify the code

Don't make changes, just give feedback.

​

Pattern 4: The documenter

I just added a new environment variable `MAX_UPLOAD_SIZE`.
Find where environment variables are documented (probably README or .env.example)
and add documentation for this one, following the existing format.

​

Pattern 5: The investigator

The app crashes when clicking "Export CSV".
Check the browser console logs I pasted below, find the source of the error,
and fix it. Test that the fix works.

[paste error logs]

​

Best practices

​

Do’s

​

Don’ts

​

When agents go off track

​

How to redirect

Wait, that's not what I meant. I want to update the existing modal,
not create a new component.

The formatting isn't right. Look at how we format errors in error-handler.ts
and match that style.

That broke things. Revert those changes and let's try a different approach.

​

Prevention: Request plans

Create a plan for adding pagination to the user list. Show me the plan
before writing code.

​

Parallel workflows: Multiple agents

​

Why this matters

​

Try it: Run two agents in parallel

1. Keep your current environment open
2. Start a second environment (new tab, go to app.ona.com and create/launch another environment for your repo)
3. In environment 1, give the agent a task:
   Report incorrect code

   Copy

   Ask AI

   Add JSDoc comments to all exported functions in backend/server.js
   and backend/data-store.js. Document parameters, return values,
   and any error responses.
   
4. In environment 2, give a different task:
   Report incorrect code

   Copy

   Ask AI

   Look at all the API endpoints in backend/server.js and create a
   document listing each endpoint, its HTTP method, expected inputs,
   and possible error responses.
   

​

Troubleshooting

• Be more specific: Name exact files or functions
• Provide context: “This is a React app using hooks, not class components”
• Reference AGENTS.md: “Follow the conventions in AGENTS.md”

• Give feedback: “That’s not right because…”
• Ask it to revert: “Undo those changes”
• Try a different prompt: “Let me rephrase…”

• Explicitly ask: “Run npm test and show me the output”
• Check if tests exist: !ls **/*.test.*
• Verify test command: !cat package.json | grep test

• Break into smaller tasks: Instead of “refactor everything,” do “refactor auth.ts first”
• Use bash commands for quick checks: !git diff instead of asking agent to summarize

• If no commits yet: !git checkout . (revert all changes)
• If committed: !git reset --hard HEAD~1 (undo last commit)
• Start fresh: Delete environment, create new one

​

What you’ve learned

• Direct agents effectively with specific, actionable prompts
• Work with agents on real development tasks (error handling, tests, refactoring)
• Use bash commands for quick context gathering
• Write prompts that get good results (be specific, reference patterns, request verification)
• Redirect agents when they go off track
• Run multiple agents in parallel to increase throughput