ATOM Documentation

← Back to App

Creating and Training Agents

Complete guide to creating, configuring, and training your AI agents.

Overview

ATOM agents are AI assistants that learn from experience and can graduate through maturity levels. This guide covers:

  • Creating your first agent
  • Configuring agent capabilities
  • Training through feedback
  • Monitoring graduation readiness
  • Promoting to higher maturity levels

Part 1: Creating Your First Agent

Step 1: Navigate to Agents

  1. Log in to https://app.atomagentos.com
  2. Click "Agents" in the left sidebar
  3. Click the "Create Agent" button

Step 2: Configure Basic Settings

Basic Information:

FieldDescriptionExample
NameAgent name (required)"Finance Assistant"
DescriptionWhat the agent does"Helps with financial analysis"
AvatarVisual representationSelect from presets or upload

Step 3: Select Agent Role

Choose what your agent specializes in:

General Assistant

  • All-purpose helper
  • Good for: General tasks, research, summarization
  • Capabilities: Web browsing, search, analysis

Finance Agent

  • Financial analysis and reporting
  • Good for: Reconciliation, forecasting, budgeting
  • Capabilities: Data analysis, report generation, calculations

Marketing Agent

  • Marketing campaigns and content
  • Good for: Social media, email campaigns, content creation
  • Capabilities: Writing, scheduling, analytics

Developer Agent

  • Code and technical tasks
  • Good for: Code review, debugging, documentation
  • Capabilities: Code analysis, testing, documentation

Custom Role

  • Define your own specialization
  • Specify custom capabilities

Step 4: Choose Initial Maturity Level

Student (Recommended for new agents)

  • ✅ Can: Read, search, browse web
  • ❌ Cannot: Make changes, send data
  • Use for: Learning, observation, research

Intern (After some training)

  • ✅ Can: Analyze, suggest, summarize
  • ❌ Cannot: Create new data, send emails
  • Use for: Analysis, recommendations

Supervised (Requires promotion)

  • ✅ Can: Create, send_email, moderate actions
  • ❌ Cannot: Delete, execute deployments
  • Use for: Most business tasks

Autonomous (Requires extensive training)

  • ✅ Can: All actions including high-risk
  • Use for: Fully automated workflows

Step 5: Create Agent

Click "Create Agent" to finish. Your agent is now ready!

Part 2: Configuring Agent Capabilities

Adding Skills

Skills determine what your agent can do:

  1. Navigate to your agent
  2. Click the "Skills" tab
  3. Browse available skills
  4. Click "Add" to assign skills

Available Skills:

Data Skills

  • web_browsing - Browse and research web
  • search - Search databases and APIs
  • analysis - Analyze data and trends
  • visualization - Create charts and graphs

Communication Skills

  • email - Send emails
  • slack - Post to Slack
  • reports - Generate reports
  • summaries - Summarize content

Business Skills

  • reconciliation - Reconcile data
  • forecasting - Predict trends
  • budgeting - Manage budgets
  • invoicing - Process invoices

Configuring Parameters

Fine-tune agent behavior:

LLM Parameters

{
  "temperature": 0.7,        // Creativity (0.0-1.0)
  "max_tokens": 2000,        // Response length
  "top_p": 0.9,              // Nucleus sampling
  "frequency_penalty": 0.0   // Reduce repetition
}

Guidelines:

  • Temperature:

    • 0.0-0.3 - Factual, precise (finance, data)
    • 0.4-0.7 - Balanced (general tasks)
    • 0.8-1.0 - Creative (writing, brainstorming)

  • Max Tokens:

    • 500-1000 - Short responses
    • 1500-2500 - Medium responses
    • 3000+ - Long, detailed responses

Part 3: Running Agent Tasks

Basic Task Execution

  1. Open your agent
  2. Type your task in the chat interface
  3. Click "Execute" (or press Enter)

Example Tasks:

Student Level:

"Search for recent articles about machine learning"
"Summarize this document"
"Find information about..."

Intern Level:

"Analyze this sales data and identify trends"
"Compare these two products"
"Suggest improvements for..."

Supervised Level:

"Draft an email to the customer about their order"
"Create a report from this data"
"Organize these files into folders"

Understanding Execution Results

After execution, you'll see:

Result:

  • Main output or response
  • Action taken (if applicable)
  • Sources or references

Reasoning Trace:

  • Step-by-step decision process
  • Alternatives considered
  • Confidence score

Metadata:

  • Execution time
  • Resources used
  • Episodes created

Part 4: Training Your Agent

Providing Feedback

Help your agent learn through feedback:

Rating Responses

👍 Thumbs Up - Positive feedback

  • Agent learns this approach works
  • Increases preference for similar patterns

👎 Thumbs Down - Negative feedback

  • Agent learns this approach doesn't work
  • Decreases preference for similar patterns

Adding Notes

  1. Click "Add Feedback"
  2. Provide detailed guidance: 
    Great analysis! Next time, focus on Q4 data only
and include visual charts.
  3. Select category:
    • accuracy - Correctness of information
    • helpfulness - Usefulness of response
    • safety - Safety and compliance
    • clarity - Clear communication

How Learning Works

Experience Recording:

Every execution creates an episode that captures:

  • Task description and context
  • Approach taken
  • Outcome (success/failure)
  • Confidence score
  • Your feedback

Pattern Recognition:

After 10+ episodes, the agent:

  • Identifies successful patterns
  • Detects failure modes
  • Generates adaptation suggestions

Adaptation:

The agent can:

  • Reinforce successful patterns
  • Avoid failed approaches
  • Calibrate confidence levels
  • Improve decision-making

Part 5: Monitoring Progress

Agent Statistics

Navigate to "Statistics" tab to see:

Performance Metrics:

  • Total executions: 150
  • Success rate: 94.6%
  • Average confidence: 0.87
  • Last execution: 2 hours ago

Learning Metrics:

  • Total experiences: 45
  • Successful patterns: 3
  • Adaptations available: 1

Graduation Readiness:

  • Current level: Student
  • Readiness score: 72%
  • Episodes until exam: 8
  • Eligible for: Intern

Graduation Readiness Formula

Readiness = (
  Zero-Intervention Ratio × 40% +
  Constitutional Compliance × 30% +
  Confidence Score × 20% +
  Success Rate × 10%
)

Component Breakdown:

Zero-Intervention Ratio (40%)

  • Agent operates without human help
  • Higher = more autonomous
  • Threshold: 40% for intern, 60% for supervised, 85% for autonomous

Constitutional Compliance (30%)

  • Adherence to safety guardrails
  • Higher = safer behavior
  • Threshold: 75% for intern, 85% for supervised, 95% for autonomous

Confidence Score (20%)

  • Well-calibrated confidence
  • Proper confidence matching actual success
  • Threshold: Varies by level

Success Rate (10%)

  • Overall task completion
  • Higher = more reliable
  • Target: >90% for all levels

Part 6: Graduation and Promotion

Understanding Graduation

Agents graduate through maturity levels based on performance:

Student → Intern

  • Requires: 70% overall readiness
  • 75% constitutional compliance
  • 40% zero-intervention

Intern → Supervised

  • Requires: 80% overall readiness
  • 85% constitutional compliance
  • 60% zero-intervention

Supervised → Autonomous

  • Requires: 95% overall readiness
  • 95% constitutional compliance
  • 85% zero-intervention

Triggering Graduation Exam

Automatic:

  • System checks eligibility every 30 episodes
  • Agent notified when ready

Manual:

  1. Navigate to agent
  2. Click "Graduation" tab
  3. If eligible, click "Trigger Exam"

The 5-Stage Graduation Exam

Stage 1: Data Collection

  • Reviews last 30 episodes
  • Extracts performance metrics
  • Validates sufficient data

Stage 2: Constitutional Compliance

  • Checks for safety violations
  • Validates compliance score
  • Must meet threshold

Stage 3: Confidence Assessment

  • Evaluates confidence calibration
  • Checks over/under-confidence
  • Must be well-calibrated

Stage 4: Success Rate

  • Calculates overall success rate
  • Analyzes failure patterns
  • Must meet threshold

Stage 5: Final Determination

  • Computes final readiness score
  • Validates all thresholds
  • Determines pass/fail

Timeline: Exam completes in < 1 second

Exam Results

Passed:

🎉 Congratulations! Your agent has graduated!

Previous Level: Student
New Level: Intern
Readiness Score: 0.72

New Capabilities Unlocked:
✓ Analyze data
✓ Suggest improvements
✓ Generate recommendations

Failed:

Exam failed. Continue training to improve readiness.

Failed Stages:
- Constitutional Compliance (72% < 75% threshold)

Recommendations:
- Focus on safety guardrails
- Review constitutional violations
- Improve compliance score

Post-Promotion Monitoring

After promotion, the system monitors performance for 7 days:

Automatic Demotion:

  • If success rate drops significantly
  • If constitutional violations occur
  • Can be disabled (manual review required)

Manual Demotion:

  • Admins can demote at any time
  • Records demotion reason
  • Agent retains learning

Part 7: Best Practices

For New Agents

  1. Start at Student Level

    • Learn agent's behavior
    • Build confidence in capabilities
    • Establish patterns

  2. Use Clear Task Descriptions

    • Be specific about requirements
    • Provide context when needed
    • Define output format

  3. Provide Consistent Feedback

    • Rate every execution
    • Add detailed notes
    • Be patient with learning

For Training Agents

  1. Focus on Specific Domains

    • Train agent on specific task types
    • Build expertise gradually
    • Don't overwhelm with variety

  2. Monitor Patterns

    • Review successful patterns
    • Address failure modes
    • Reinforce good behavior

  3. Graduate at Right Time

    • Don't rush graduation
    • Ensure readiness score is solid
    • Verify constitutional compliance

For Mature Agents

  1. Continue Monitoring

    • Watch performance post-promotion
    • Provide ongoing feedback
    • Adjust capabilities as needed

  2. Expand Capabilities

    • Add new skills gradually
    • Test in safe environments
    • Monitor impact on performance

  3. Maintain Safety

    • Review constitutional compliance
    • Audit high-risk actions
    • Adjust maturity level if needed

Part 8: Troubleshooting

Agent Not Learning

Symptoms:

  • Repeated mistakes
  • Low success rate
  • Poor pattern recognition

Solutions:

  1. Provide more explicit feedback
  2. Focus on specific task types
  3. Review and rate past executions
  4. Ensure sufficient episodes (30+)

Graduation Exam Fails

Symptoms:

  • Exam fails consistently
  • Low readiness score

Solutions:

  1. Check which stage failed
  2. Address specific weakness
  3. Continue training
  4. Trigger exam again later

Poor Performance After Promotion

Symptoms:

  • Success rate drops after graduation
  • New errors appear

Solutions:

  1. Review new capabilities
  2. Provide additional training
  3. Consider demotion if severe
  4. Adjust task complexity

Advanced Topics

Custom Agent Roles

Create specialized agents for your domain:

  1. Select "Custom Role" when creating
  2. Define custom capabilities
  3. Specify task types
  4. Configure parameters

Multi-Agent Coordination

Have multiple agents work together:

  1. Create specialized agents
  2. Define clear responsibilities
  3. Use cross-agent coordination
  4. Monitor joint performance

Integration with External Systems

Connect agents to your tools:

  1. Navigate to "Integrations"
  2. Connect required services
  3. Grant permissions to agents
  4. Test integrations safely

Next Steps

Last Updated: 2025-02-06 Version: 1.0.0