ai agentic systems

Chatbot:
User: "Cách fix NullPointerException?"
Bot:  "Check null trước khi access..." → DONE

AI Agent:
User: "Fix bug PORTAL-123"
Agent: (thinking) "Cần hiểu bug → đọc ticket → xem code → tìm root cause → fix → test → PR"
 Step 1: Đọc Jira ticket PORTAL-123 → hiểu symptom
 Step 2: Tìm file liên quan trong codebase
 Step 3: Đọc code, identify root cause
 Step 4: Viết fix
 Step 5: Chạy tests
 Step 6: Tests fail → đọc error → sửa lại
 Step 7: Tests pass → tạo PR
 → DONE (multi-step, self-correcting)

Level 0: Chatbot          → Q&A, no actions
Level 1: Tool-augmented   → Answer + call 1 tool khi cần
Level 2: Multi-step agent → Plan + execute sequence of tools
Level 3: Autonomous agent → Self-plan, self-correct, handle errors, create sub-goals
Level 4: Multi-agent      → Nhiều agents collaborate, delegate, review nhau

User: "Refactor UserService to use Clean Architecture"

PLAN:
1. Read current UserService and dependencies
2. Create domain layer (entities, ports)
3. Create use case layer
4. Create adapter layer (current service becomes adapter)
5. Update controller to use ports
6. Move tests to match new structure
7. Run tests, fix issues
8. Verify no regressions

EXECUTION:
[Step 1] Reading files... ✓
[Step 2] Creating domain/model/User.java... ✓
[Step 3] Creating domain/port/UserRepository.java... ✓
[Step 4] Oh, UserService also depends on EmailService → revise plan
REVISED PLAN: Add step 3.5: Create NotificationPort
[Step 3.5] Creating domain/port/NotificationPort.java... ✓
...

Main Agent: "Build user registration feature"
 ├── Sub-task 1: "Design data model" → Research Agent
 ├── Sub-task 2: "Implement API endpoint" → Coding Agent
 ├── Sub-task 3: "Write tests" → Testing Agent
 └── Sub-task 4: "Update documentation" → Docs Agent

1. Sequential Pipeline:
  Research → Code → Test → Review → Deploy
  (mỗi agent output = input cho agent tiếp)

2. Collaborative:
  Coder writes → Reviewer feedback → Coder revises → Reviewer approves
  (iterative loop giữa 2 agents)

3. Hierarchical:
  Orchestrator delegates subtasks → sub-agents report back
  (tree structure)

4. Debate:
  Agent A proposes solution → Agent B critiques → Agent A defends/revises
  (adversarial — better quality through disagreement)

Input: Natural language requirement
Process: Understand → Plan → Generate code → Run tests → Iterate
Output: Working code with tests

Tools needed: file read/write, run tests, search codebase, get diagnostics

Input: Bug report (Jira ticket, error log)
Process: Read report → Find relevant code → Reproduce → Identify root cause → Suggest fix
Output: Root cause analysis + proposed fix

Tools needed: Jira (read ticket), codebase search, file read, run tests

Input: Git diff / Pull Request
Process: Read changes → Check quality → Identify issues → Suggest improvements
Output: Review comments

Tools needed: Git diff, file read, run linter, security scan

Input: Code changes or feature spec
Process: Read code → Understand intent → Generate/update docs → Verify accuracy
Output: Updated documentation

Tools needed: file read/write, search, Confluence API

Input: Feature idea
Process:
 Phase 1: Generate requirements (ask clarifying questions)
 Phase 2: Design architecture
 Phase 3: Create task breakdown
 Phase 4: Implement tasks (code + test each)
 Phase 5: Review implementation
Output: Complete feature with docs and tests

Tools needed: ALL (file ops, tests, git, Jira, Confluence, web search)

// Agent thinks test passed but actually read old output
THOUGHT: "Tests pass, I'm done"
REALITY: Tests were from previous run, current code has bug

// Mitigation: ALWAYS re-run, never trust cached results

Iteration 5: Try approach A → fails
Iteration 6: Try approach A (slightly different) → fails
Iteration 7: Try approach A (again) → fails
...

// Mitigation: Loop detection, max iterations, escalate after N failures

// Mitigation strategies:
1. Summarize completed steps (compress context)
2. External memory (write notes to file, read when needed)
3. Task decomposition (smaller subtasks = less context per subtask)
4. Context compaction (automatic in modern systems)

// Dangerous: Agent decides to "clean up" by deleting files
// Dangerous: Agent runs `rm -rf` thinking it's temp directory
// Dangerous: Agent pushes directly to main branch

// Mitigation:
1. Approval gates (human confirms before destructive actions)
2. Sandboxing (agent operates in isolated environment)
3. Guardrails (system prompt: "never delete without confirmation")
4. Reversibility preference (prefer reversible actions)

Good system prompt includes:
1. Identity: "You are a senior Java developer..."
2. Capabilities: "You can read files, write code, run tests..."
3. Constraints: "Never push to main, always run tests before claiming done"
4. Workflow: "Read before writing, test after coding, verify before reporting"
5. Style: "Match existing code style, follow project conventions"
6. Failure handling: "If stuck after 2 attempts, try different approach"

Good tool design:
- Clear, specific descriptions (AI uses description to decide WHEN to use)
- Atomic actions (1 tool = 1 thing)
- Informative return values (agent needs to understand result)
- Error messages that guide next action
- Idempotent where possible

Bad tool design:
- Vague description: "Do stuff with files" (when does AI use this?)
- God tool: "manage_everything(action, params)" (too many options)
- Silent failures: return empty on error (agent thinks success)

How to measure agent quality:
1. Task completion rate (% tasks fully completed correctly)
2. Iteration efficiency (steps needed vs optimal)
3. Error recovery rate (% of errors self-corrected)
4. Tool usage accuracy (right tool, right params)
5. Safety (0 destructive unintended actions)

Improvement loop:
1. Collect failed tasks
2. Analyze failure patterns (wrong tool? bad reasoning? missing context?)
3. Improve: system prompt, tool descriptions, or add new tools
4. Re-test