TM AI Agent

TM AI Agent memungkinkan Anda untuk mendefinisikan dan mengelola agent AI yang bertindak sebagai komponen AI modular dan bertugas khusus dalam sistem Anda. Agent ini dirancang untuk melakukan tugas otomatis, memproses data, dan berintegrasi dengan trigger sistem untuk automasi end-to-end.

Memahami DocType TM AI Agent

Tujuan: TM AI Agent mendefinisikan struktur dan konfigurasi agent AI dalam aplikasi Frappe yang bekerja secara otomatis di background. Agent ini biasanya digunakan untuk memproses data, melakukan tugas cerdas, atau menggabungkan berbagai perilaku AI dalam alur kerja yang kompleks. Berbeda dengan TM AI Chat Agent yang interaktif, TM AI Agent bekerja secara autonomous berdasarkan trigger, schedule, atau on-demand execution.

Fungsi: DocType ini memungkinkan Anda mengkonfigurasi agent untuk berbagai skenario automasi, termasuk responding ke DocType events (create, update, delete), scheduled execution (daily, weekly, hourly), atau manual on-demand runs. Agent dapat menggunakan tools untuk berinteraksi dengan sistem, mengakses vector database untuk knowledge retrieval, menggunakan agentic loop untuk task yang kompleks, dan dilengkapi dengan evaluation dan guardrail untuk quality control dan security.

Role yang Diperlukan

• System Manager - Akses penuh untuk create, read, update, delete, dan mengelola TM AI Agent

Field TM AI Agent

AI Agent Section

LLM Section (Hidden)

Loop Configuration Section

Image Generation Section

Video Generation Section

Search Knowledge Section

Tab: Evaluation

Evaluation Settings Section

Evaluation Rules Section

Scores Section

Tab: Guards

Guard Settings Section

Guard Rules Section

Prosedur

1. Navigate ke TechMaju AI Module > TM AI Agent

Akses daftar agent dari modul TechMaju AI di workspace Anda atau langsung navigate ke /app/tm-ai-agent.

2. Menambahkan TM AI Agent Baru

Langkah 2.1: Klik '+ Add TM AI Agent'

Ini membuka form pembuatan agent.

Langkah 2.2: Isi Informasi AI Agent

Basic Configuration: - Agent Name: Masukkan nama yang descriptive dan unique - Contoh: "Daily Sales Report Generator" - Contoh: "Customer Order Processor" - Contoh: "Inventory Level Monitor" - AI Model: Pilih model AI yang sesuai - Gunakan powerful models (GPT-4) untuk complex reasoning - Gunakan faster models (GPT-3.5) untuk simple processing - Application: Pilih aplikasi yang sesuai (untuk non-system agents) - Field ini tidak dapat diubah setelah agent dibuat - Active: Centang untuk activate agent - Leave unchecked jika masih dalam development/testing

Trigger Configuration (Optional): - From Trigger: Centang jika agent harus respond ke DocType events - Trigger DocType: Pilih DocType yang akan trigger agent - Contoh: "Sales Order" untuk process orders automatically - Contoh: "Customer" untuk handle customer onboarding - Contoh: "Task" untuk automate task management

System Generated: - Leave unchecked untuk custom agents - Only checked untuk agents created by system

3. Mengkonfigurasi Agent Context dan Instructions

Langkah 3.1: Tulis Agent Context

Agent Context adalah system prompt yang defines behavior. Write clearly dan specifically:

Anda adalah automated agent yang bertugas menghasilkan daily sales report.

Tugas Anda:
1. Query sales data untuk hari sebelumnya dari Sales Order DocType
2. Calculate total revenue, order count, dan average order value
3. Identify top 5 selling products
4. Generate formatted report dengan insights
5. Create Report document dengan hasilnya

Format Output:
- Gunakan struktured format dengan sections yang jelas
- Include numeric data dengan proper formatting
- Provide brief analysis dan recommendations
- Highlight any anomalies atau concerns

Batasan:
- Hanya process data untuk hari sebelumnya
- Jangan modify atau delete existing records
- Jika error terjadi, log details dan notify administrator

Best Practices untuk Agent Context: - Jelaskan purpose agent dengan sangat spesifik - List semua steps yang harus agent lakukan - Define expected output format - Set clear boundaries tentang what agent can dan cannot do - Include error handling instructions

Langkah 3.2: Tambahkan Additional Context

• Click pada field Additional Context
• Select relevant context sets dari TM AI Agent Context
• Context berguna untuk:
  • Business rules dan policies
  • Reference data (product lists, price tables)
  • Template documents
  • Company-specific guidelines

Langkah 3.3: Attach Tools

• Select tools yang agent butuhkan untuk perform tasks
• Common tools untuk automated agents:
  • Query Document Tool: Untuk read data dari DocTypes
  • Create Document Tool: Untuk create new records
  • Update Document Tool: Untuk modify existing records
  • Email Tool: Untuk send notifications
  • API Call Tool: Untuk integrate dengan external systems
  • File Processing Tool: Untuk handle attachments

Tool Selection Strategy: - Only attach tools yang benar-benar dibutuhkan - Consider security implications dari each tool - Test tools individually sebelum attaching ke agent

4. Configure Loop Execution (Advanced)

Untuk tasks yang require multi-step reasoning atau self-correction:

Langkah 4.1: Enable Loop

• Centang "Enable Loop"
• Loop mode enables agentic reasoning patterns:
  • Plan → Execute → Reflect → Adjust → Repeat

Langkah 4.2: Set Loop Parameters

• Max Iterations: Set appropriate limit (3-5 untuk most cases)
  • Higher values untuk complex analysis
  • Lower values untuk simple processing
• Stop On Task Complete: Centang untuk efficiency
  • Agent akan stop ketika determines task is complete
  • Prevents unnecessary iterations

Langkah 4.3: Add Skills (Optional)

• Skills are pre-packaged combinations dari tools dan contexts
• Select relevant skills untuk agent's domain:
  • "Data Analysis Skill" untuk analysis tasks
  • "Report Generation Skill" untuk report creation
  • "Customer Service Skill" untuk customer interactions

When to Use Loop: - Complex data analysis requiring multiple passes - Tasks requiring validation dan correction - Scenarios where agent needs to adapt strategy - Multi-step workflows dengan decision points

When NOT to Use Loop: - Simple, straightforward processing - Time-sensitive operations (loop adds latency) - Tasks dengan well-defined linear steps

5. Configure Media Generation (Optional)

Jika agent bertugas generate images atau videos:

For Image Generation:

• Image Prompt: Describe image yang ingin generated
• Image Ratio: Set aspect ratio (1:1, 16:9, dll)
• Image Width/Height: Specify dimensions
• Image Seed: Set untuk reproducibility
• Image Guidance Scale: Adjust untuk control adherence ke prompt

For Video Generation:

• Video Prompt: Describe video sequence
• Camera Fixed: Decide jika camera static atau moving
• First/Last Frame Image: Guide video generation
• Resolution: Set quality level
• Video Ratio: Set aspect ratio
• Duration: Specify length dalam seconds
• Video Seed: Set untuk reproducibility

6. Configure Search Knowledge (Optional)

Jika agent needs access ke knowledge base:

Langkah 6.1: Enable Vector DB

• Centang "Use Vector DB"
• This enables semantic search di knowledge base

Langkah 6.2: Set Search Scope (Optional)

• Select VectorDB Search Scope untuk filter results
• Scopes help dengan:
  • Limiting search ke relevant documents
  • Improving performance
  • Ensuring appropriate access control
• Leave empty untuk search entire knowledge base

Use Cases untuk Vector DB: - Agent needs reference documentation - Policy compliance checking - Finding similar past cases - Knowledge-augmented decision making

7. Configure Evaluation (Optional)

Untuk monitor dan improve agent quality:

Langkah 7.1: Navigate ke Evaluation Tab

• Click pada tab "Evaluation"

Langkah 7.2: Enable Evaluation

• Centang "Enable Evaluation"
• Evaluation provides automated quality assessment

Langkah 7.3: Add Evaluation Rules

• Select rules dari TM AI Eval Rule Item
• Common evaluation criteria:
  • Task Completion: Did agent complete the task?
  • Accuracy: Are results correct?
  • Efficiency: How many iterations needed?
  • Output Quality: Is formatting proper?
  • Policy Compliance: Does output follow rules?

Langkah 7.4: Monitor Scores

• Review scores di Eval Scores section
• Use scores untuk:
  • Identify areas untuk improvement
  • Compare different agent configurations
  • Track quality trends over time
  • Justify agent ROI

8. Configure Guards (Optional)

Untuk ensure safety dan compliance:

Langkah 8.1: Navigate ke Guards Tab

• Click pada tab "Guards"

Langkah 8.2: Enable Guards

• Centang "Enable Guard"
• Guards provide safety layer

Langkah 8.3: Add Guard Rules

• Click "Add Row" di Guard Rules table
• Configure rules seperti:
  • Action Restrictions: Prevent certain operations
  • Data Validation: Ensure data meets requirements
  • Rate Limiting: Prevent excessive operations
  • Approval Required: Mandate human review
  • Notification Triggers: Alert on specific conditions

Langkah 8.4: Monitor Guard Logs

• Review logs di Guard Logs section
• Track:
  • When guards triggered
  • What actions were blocked
  • Why rules activated
  • Frequency of violations

9. Save dan Test Agent

Langkah 9.1: Save Agent

• Click Save button
• Verify no validation errors

Langkah 9.2: Test Agent Execution

For On-Demand Agents: - Click "Run Agent" button di form - Provide test Request/Prompt - If From Trigger enabled, specify Trigger Document - Click Execute - Review output di TM AI Agent Run record

For Trigger-Based Agents: - Create atau update test record di Trigger DocType - Verify agent triggered automatically - Check TM AI Agent Run untuk results

For Scheduled Agents: - Configure schedule via TM AI Schedule - Wait untuk scheduled execution atau trigger manually - Review execution logs

Langkah 9.3: Review Results

• Navigate ke TM AI Agent Run list
• Find your agent's runs
• Check:
  • Request dan Response content
  • Total Iterations (jika loop enabled)
  • Stop Reason
  • Any errors atau warnings

Langkah 9.4: Iterate dan Improve

• Based on test results:
  • Refine Agent Context untuk better performance
  • Adjust tool selection
  • Optimize loop parameters
  • Fine-tune evaluation rules
  • Update guard configurations

Best Practices

Agent Design Principles

1. Single Responsibility: Design agent untuk do one thing well. Complex workflows should use multiple agents coordinated via triggers atau schedules.

2. Idempotency: Design agents to be idempotent when possible - running multiple times dengan same input should produce same result without side effects.

3. Error Handling: Always include explicit error handling instructions:

   • What to do ketika data tidak available
   • How to handle unexpected formats
   • When to notify humans
   • How to log errors

4. Context Length Management: Keep Agent Context concise. Use Additional Context untuk large reference data rather than embedding everything di main context.

5. Tool Minimalism: Only attach tools yang truly needed. Extra tools:

   • Increase confusion untuk LLM
   • Create security risks
   • Slow down execution

Performance Optimization

1. Model Selection Strategy:

   • Use lighter models untuk simple, well-defined tasks
   • Reserve GPT-4 atau advanced models untuk:
     • Complex reasoning
     • Ambiguous situations
     • Creative generation
     • Multi-step planning

2. Loop Configuration:

   • Start dengan lower Max Iterations (3)
   • Increase only if agent consistently needs more
   • Monitor actual iterations used via TM AI Agent Run
   • Set Stop On Task Complete = true untuk efficiency

3. Vector DB Usage:

   • Only enable jika agent truly benefits dari knowledge retrieval
   • Use specific Search Scopes untuk reduce search space
   • Consider caching frequently accessed knowledge di Additional Context

4. Trigger Optimization:

   • Be specific tentang DocType events yang trigger agent
   • Use filters di trigger configuration untuk reduce unnecessary runs
   • Consider batching multiple triggers instead of processing individually

Security dan Compliance

1. Tool Access Control:

   • Apply principle of least privilege
   • Audit tool permissions regularly
   • Create role-specific tool sets
   • Never grant tools broader access than needed

2. Data Sensitivity:

   • Never include sensitive data (passwords, API keys, PII) di Agent Context
   • Use encrypted field types untuk sensitive configurations
   • Implement guards untuk prevent accidental data exposure
   • Log all data access untuk audit trails

3. Guard Strategy:

   • Enable guards untuk production agents
   • Test guards dengan edge cases
   • Balance security dengan usability
   • Review guard logs untuk identify false positives

4. Evaluation untuk Compliance:

   • Create evaluation rules yang check compliance
   • Monitor scores untuk policy violations
   • Set thresholds untuk automatic alerts
   • Review failed evaluations promptly

Maintenance dan Monitoring

1. Regular Reviews:

   • Review TM AI Agent Run records weekly
   • Analyze success rates dan error patterns
   • Check evaluation scores trends
   • Monitor guard violation frequencies

2. Iterative Improvement Cycle:

   Monitor → Analyze → Adjust → Test → Deploy → Monitor

   • Track key metrics (completion rate, iteration count, evaluation scores)
   • Identify common failure modes
   • Update Agent Context based on learnings
   • A/B test configuration changes

3. Documentation:

   • Document agent purpose dan use cases
   • Keep changelog dari configuration updates
   • Note any quirks atau known limitations
   • Share learnings dengan team

4. Version Control:

   • Use Update Set untuk track configuration changes
   • Test di development environment first
   • Have rollback plan untuk production deployments
   • Backup working configurations

Integration Patterns

1. Agent Chains:

   • Connect agents via triggers:
     • Agent A creates Record X
     • Record X creation triggers Agent B
     • Agent B updates Record Y
     • etc.

2. Human-in-the-Loop:

   • Design approval workflows:
     • Agent generates draft
     • Human reviews dan approves
     • Upon approval, agent completes task

3. Batch Processing:

   • Schedule agents untuk off-peak hours
   • Process records in batches
   • Use loop untuk iterate through items

4. Event-Driven Architecture:

   • Use triggers untuk respond ke business events
   • Chain agents untuk complex workflows
   • Leverage vector DB untuk shared knowledge

Use Cases dan Examples

1. Daily Report Generator

Configuration: - Agent Name: "Daily Sales Summary Generator" - AI Model: GPT-3.5 (sufficient untuk structured reporting) - From Trigger: No (scheduled execution) - Agent Context: Generate daily sales summary dari Sales Order - Tools: Query Document, Create Document (untuk Report) - Enable Loop: No (straightforward task) - Evaluation: Enabled (check completeness dan accuracy)

How It Works: 1. Scheduled via TM AI Schedule untuk run every day at 8 AM 2. Agent queries Sales Orders dari previous day 3. Calculates metrics (total revenue, order count, etc.) 4. Generates formatted report 5. Creates Report document dengan results 6. Evaluation checks report completeness

2. Customer Onboarding Automator

Configuration: - Agent Name: "New Customer Onboarding Agent" - AI Model: GPT-4 (untuk handle variations) - From Trigger: Yes - Trigger DocType: Customer - Agent Context: Automate onboarding steps untuk new customers - Tools: Query Document, Create Document, Email Tool - Enable Loop: Yes (untuk handle multi-step process) - Max Iterations: 5 - Guards: Enabled (ensure proper data validation)

How It Works: 1. Triggered ketika new Customer record created 2. Agent validates customer data 3. Creates necessary related records (addresses, contacts) 4. Sends welcome email 5. Creates initial tasks untuk account manager 6. Guards ensure all required data present before proceeding

3. Document Classification Agent

Configuration: - Agent Name: "Invoice Document Classifier" - AI Model: GPT-4 - From Trigger: Yes - Trigger DocType: File (dengan filters untuk invoices) - Agent Context: Extract dan classify invoice data - Tools: File Reading Tool, Create Document Tool - Use Vector DB: Yes (untuk lookup vendor patterns) - Search Scope: "Invoice Templates" - Enable Loop: Yes (untuk correction jika extraction fails)

How It Works: 1. Triggered when invoice file uploaded 2. Agent reads file content 3. Searches vector DB untuk similar invoices 4. Extracts key information (vendor, amount, date) 5. Creates Purchase Invoice record 6. Links original file 7. Loop allows retry jika extraction uncertain

4. Data Quality Monitor

Configuration: - Agent Name: "Customer Data Quality Monitor" - AI Model: GPT-3.5 - From Trigger: No (scheduled hourly) - Agent Context: Check customer data untuk quality issues - Tools: Query Document, Update Document, Email Tool - Enable Loop: No - Evaluation: Enabled (track detection accuracy) - Guards: Enabled (prevent incorrect modifications)

How It Works: 1. Scheduled hourly execution 2. Queries Customer records updated recently 3. Checks untuk common issues (missing phone, invalid email) 4. Flags records dengan issues 5. Notifies data team via email 6. Evaluation tracks detection accuracy over time

Troubleshooting

Agent Tidak Triggered

Gejala: Agent dengan From Trigger enabled tidak run ketika expected

Penyebab dan Solusi: - Agent Not Active: Verify Active checkbox checked - Wrong Trigger DocType: Confirm Trigger DocType matches actual DocType being modified - Event Type: Agent triggers on afterinsert, aftersave, on_update - verify your use case matches - Permissions: Ensure agent has permission untuk access Trigger DocType - Server Issues: Check Error Log untuk any system errors

Loop Tidak Converging

Gejala: Loop iterations hit Max Iterations without completing

Solusi: - Unclear Task Definition: Make Agent Context more specific tentang completion criteria - Insufficient Tools: Ensure agent has all tools needed untuk complete task - Too Low Max Iterations: Increase Max Iterations jika task genuinely complex - Stop On Task Complete Logic: Review jika agent properly recognizing completion - Review Iterations: Check TM AI Agent Run iterations field untuk see what agent attempted

Poor Evaluation Scores

Gejala: Agent consistently scores low pada evaluations

Solusi: - Mismatch Between Context dan Task: Align Agent Context dengan actual task requirements - Insufficient Context: Add relevant Additional Context - Wrong Tools: Review tool selection dan capabilities - Evaluation Rules Too Strict: Adjust evaluation criteria jika unrealistic - Model Limitations: Consider upgrading ke more powerful AI Model

Guard Blocking Valid Actions

Gejala: Guards block actions yang seharusnya allowed

Solusi: - Review Guard Rules: Check rules untuk overly restrictive conditions - Adjust Thresholds: Fine-tune numeric thresholds di rules - Add Exceptions: Create exception rules untuk valid edge cases - Monitor Patterns: Look untuk patterns dalam false positives - Guard Logs: Use Guard Logs HTML untuk investigate specific blocks

High Token Usage / Cost

Gejala: Agent consuming excessive tokens

Solusi: - Reduce Context Length: Trim unnecessary information dari Agent Context - Optimize Additional Context: Remove atau reduce verbose context sets - Limit Tool Descriptions: Ensure tool descriptions concise - Disable Unnecessary Features: Turn off Vector DB jika not providing value - Model Downgrade: Switch ke cheaper model jika task allows - Batch Operations: Process multiple items per run instead of separate runs

Inconsistent Results

Gejala: Agent produces different outputs untuk same input

Solusi: - Temperature Settings: Check AI Model temperature configuration - Non-Deterministic Tools: Some tools may have randomness - review tool behavior - Timing Issues: Results vary based on external data changes - Loop Variability: Different iteration paths dalam loop lead to variations - Add Constraints: Make Agent Context more prescriptive tentang expected output format

Related Features

• TM AI Model: LLM models yang power agents
• TM AI Agent Context: Reusable context sets untuk agent knowledge
• TM AI Agent Tool: Tools untuk agent capabilities
• TM AI Skill: Bundled tools dan contexts untuk domain tasks
• TM AI Schedule: Schedule agent execution
• TM AI Trigger: Configure DocType event triggers
• TM AI Agent Run: Execution records dan logs
• TM AI Eval Rule: Evaluation criteria
• TM AI Guard Agent Rule: Safety rules
• VectorDB Search Scope: Knowledge base search configuration

Technical Notes

Agent Execution Flow

1. Agent triggered (manually, schedule, atau DocType event)
2. System loads agent configuration
3. Constructs prompt dengan Agent Context + Additional Context
4. If Vector DB enabled, performs semantic search
5. Adds search results ke context
6. If Loop enabled, enters iteration cycle:
   • Plan next step
   • Execute using available tools
   • Reflect on results
   • Decide continue atau stop
7. Generates final response
8. If Evaluation enabled, assesses quality
9. If Guards enabled, validates output
10. Records results di TM AI Agent Run
11. Triggers any downstream actions

Loop Mechanics

Loop uses ReAct (Reasoning + Acting) pattern: Thought: What do I need to do? Action: Execute tool Observation: What was the result? Thought: Is task complete? [Repeat atau Finish]

Agent has full control over: - Which tools to call - What parameters to use - When to stop

Tool Execution

Tools are called via function calling: 1. Agent decides tool needed 2. Generates tool call dengan parameters 3. System executes tool 4. Result returned ke agent 5. Agent continues dengan new information

Vector DB Integration

When enabled: 1. Agent's request analyzed untuk key concepts 2. Semantic search performed di knowledge base 3. Top N relevant chunks retrieved 4. Chunks added ke agent's context 5. Agent uses knowledge untuk inform response

Evaluation System

Post-execution: 1. Agent's Request dan Response captured 2. Evaluation rules applied 3. Each rule generates score (0-100) 4. Scores aggregated dan stored 5. Trends tracked over time 6. Alerts triggered untuk low scores

Guard System

Guards operate at two levels: 1. Pre-Execution: Validate inputs dan parameters 2. Post-Execution: Check outputs before committing

Guards can: - Block execution entirely - Modify parameters - Require approval - Log warnings - Trigger notifications

Terakhir Diperbarui: Januari 2026
Versi: 2.0
Modul: TechMaju AI