Docs
Core Concepts
Understanding AI Agents

Understanding AI Agents

AI Agents are autonomous systems that perceive their environment, make decisions, and take actions to achieve specific goals.

What is an AI Agent?

An AI Agent is a software system that:

  1. Perceives - Receives inputs from users, systems, or environment
  2. Reasons - Uses AI/LLM to understand and make decisions
  3. Acts - Takes actions to achieve goals (API calls, responses, tool usage)
  4. Learns - Adapts based on feedback and outcomes
Input → Perception → Reasoning → Action → Output
   ↑                                        ↓
   └────────── Feedback Loop ───────────────┘

Agent Characteristics

Autonomy

Agents operate independently without continuous human intervention:

# Agent autonomously handles multi-step tasks
agent = CustomerSupportAgent()
result = agent.handle_customer_query(
    "I need to return my order and get a refund"
)
# Agent will:
# 1. Verify order details
# 2. Check return policy
# 3. Initiate return process
# 4. Process refund
# 5. Send confirmation

Reactivity

Agents respond to changes in their environment:

agent.on('new_message', async (message) => {
  const context = await agent.analyzeContext(message)
  const response = await agent.generateResponse(context)
  await agent.send(response)
})

Pro-activeness

Agents take initiative to achieve goals:

# Agent proactively identifies issues
if order.status == 'delayed' and days_delayed > 3:
    agent.notify_customer(order)
    agent.offer_compensation(order)
    agent.escalate_to_support(order)

Social Ability

Agents communicate with other agents and humans:

// Multi-agent collaboration
const orderAgent = new OrderAgent()
const inventoryAgent = new InventoryAgent()
const shippingAgent = new ShippingAgent()
 
// Agents coordinate to fulfill order
const order = await orderAgent.create(orderData)
const stock = await inventoryAgent.reserve(order.items)
const shipment = await shippingAgent.schedule(order, stock)

Types of AI Agents

1. Simple Reflex Agents

Respond directly to inputs based on rules:

if (query.includes('order status')) {
  return getOrderStatus(userId)
}
if (query.includes('cancel order')) {
  return cancelOrder(orderId)
}

Use Cases: Simple chatbots, rule-based systems

2. Model-Based Agents

Maintain internal state and model of the world:

class CustomerSupportAgent:
    def __init__(self):
        self.conversation_history = []
        self.customer_context = {}
    
    def handle_query(self, query):
        # Uses conversation history for context
        self.conversation_history.append(query)
        context = self.build_context()
        response = self.llm.generate(query, context)
        return response

Use Cases: Conversational AI, context-aware assistants

3. Goal-Based Agents

Work towards specific goals:

const agent = new GoalBasedAgent({
  goal: 'resolve_customer_issue',
  maxSteps: 10
})
 
await agent.run({
  query: "My order hasn't arrived",
  customerId: '123'
})
 
// Agent will try different actions until goal is achieved:
// 1. Check order status
// 2. Track shipment
// 3. Contact carrier
// 4. Offer solutions
// 5. Verify customer satisfaction

Use Cases: Task completion, problem-solving systems

4. Utility-Based Agents

Optimize for specific metrics or utility functions:

class UtilityAgent:
    def select_action(self, state, possible_actions):
        # Evaluate each action's expected utility
        utilities = [
            self.calculate_utility(action, state)
            for action in possible_actions
        ]
        # Select action with highest utility
        return possible_actions[argmax(utilities)]
    
    def calculate_utility(self, action, state):
        return (
            0.4 * customer_satisfaction +
            0.3 * cost_efficiency +
            0.3 * time_to_resolution
        )

Use Cases: Optimization systems, resource allocation

5. Learning Agents

Improve performance over time:

class LearningAgent {
  async handleQuery(query: string) {
    const response = await this.generateResponse(query)
    
    // Collect feedback
    const feedback = await this.getFeedback(response)
    
    // Learn from feedback
    await this.updateModel(query, response, feedback)
    
    return response
  }
}

Use Cases: Personalization, adaptive systems

Agent Architectures

ReAct (Reasoning + Acting)

Interleaves reasoning and acting:

def react_agent(query):
    while not task_complete:
        # Thought: Reason about what to do
        thought = llm.generate(f"Thought: {query}")
        
        # Action: Decide and take action
        action = llm.generate(f"Action: {thought}")
        result = execute_action(action)
        
        # Observation: Observe result
        observation = f"Observation: {result}"
        
        # Continue or conclude
        if is_answer_complete(observation):
            break
    
    return final_answer

Chain of Thought (CoT)

Breaks down complex reasoning:

const result = await agent.run({
  prompt: "Calculate the total cost",
  strategy: 'chain-of-thought'
})
 
// Agent thinking process:
// Step 1: Identify all items → [item1, item2, item3]
// Step 2: Get price for each → [$10, $15, $20]
// Step 3: Sum prices → $45
// Step 4: Add tax (10%) → $49.50
// Final Answer: $49.50

Tree of Thoughts (ToT)

Explores multiple reasoning paths:

def tree_of_thoughts(problem):
    # Generate multiple solution paths
    paths = []
    for thought in generate_thoughts(problem):
        score = evaluate_thought(thought)
        if score > threshold:
            paths.append(explore_path(thought))
    
    # Select best path
    best_path = max(paths, key=lambda p: p.score)
    return best_path.solution

Multi-Agent Systems

Multiple agents collaborate:

class MultiAgentSystem {
  agents = {
    coordinator: new CoordinatorAgent(),
    researcher: new ResearchAgent(),
    writer: new WriterAgent(),
    editor: new EditorAgent()
  }
  
  async execute(task: string) {
    // Coordinator breaks down task
    const subtasks = await this.agents.coordinator.plan(task)
    
    // Research agent gathers information
    const research = await this.agents.researcher.gather(subtasks)
    
    // Writer creates content
    const draft = await this.agents.writer.create(research)
    
    // Editor refines output
    const final = await this.agents.editor.refine(draft)
    
    return final
  }
}

Agent Components

1. Perception Layer

Processes inputs and extracts information:

class PerceptionLayer:
    def process_input(self, raw_input):
        # Parse and understand input
        intent = self.classify_intent(raw_input)
        entities = self.extract_entities(raw_input)
        sentiment = self.analyze_sentiment(raw_input)
        
        return {
            'text': raw_input,
            'intent': intent,
            'entities': entities,
            'sentiment': sentiment
        }

2. Memory

Stores and retrieves information:

class AgentMemory {
  shortTerm: ConversationHistory
  longTerm: VectorDatabase
  
  async remember(key: string, value: any) {
    // Store in short-term
    this.shortTerm.add(key, value)
    
    // Index in long-term
    await this.longTerm.index(key, value)
  }
  
  async recall(query: string) {
    // Check short-term first
    const recent = this.shortTerm.get(query)
    if (recent) return recent
    
    // Search long-term memory
    return await this.longTerm.search(query)
  }
}

3. Reasoning Engine

Makes decisions:

class ReasoningEngine:
    def decide(self, context, options):
        # Analyze situation
        analysis = self.analyze(context)
        
        # Evaluate options
        evaluations = [
            self.evaluate(option, analysis)
            for option in options
        ]
        
        # Select best option
        best_option = max(evaluations, key=lambda x: x.score)
        
        return best_option.action

4. Action Executor

Performs actions:

class ActionExecutor {
  tools = {
    'search': new SearchTool(),
    'calculate': new CalculatorTool(),
    'database': new DatabaseTool(),
    'api': new APITool()
  }
  
  async execute(action: Action) {
    const tool = this.tools[action.tool]
    
    try {
      const result = await tool.run(action.params)
      return { success: true, result }
    } catch (error) {
      return { success: false, error }
    }
  }
}

Monitoring Agents with AgenticAnts

Basic Agent Monitoring

import { AgenticAnts } from '@agenticants/sdk'
 
const ants = new AgenticAnts({ apiKey: process.env.AGENTICANTS_API_KEY })
 
class MonitoredAgent {
  async run(input: string) {
    // Start trace
    const trace = await ants.trace.create({
      name: 'customer-support-agent',
      input: input,
      metadata: {
        agentType: 'support',
        version: '1.0.0'
      }
    })
    
    try {
      // Agent execution
      const result = await this.process(input, trace)
      
      // Complete trace
      await trace.complete({
        output: result,
        metadata: {
          success: true,
          steps: this.steps.length
        }
      })
      
      return result
    } catch (error) {
      await trace.error({ error: error.message })
      throw error
    }
  }
}

Multi-Step Agent Monitoring

from agenticants import AgenticAnts
 
ants = AgenticAnts(api_key=os.getenv('AGENTICANTS_API_KEY'))
 
class MultiStepAgent:
    def run(self, query):
        # Create parent trace
        trace = ants.trace.create(name='multi-step-agent', input=query)
        
        # Step 1: Classification
        classification_span = trace.span('classify-intent')
        intent = self.classify(query)
        classification_span.end(output=intent)
        
        # Step 2: Retrieval
        retrieval_span = trace.span('retrieve-context')
        context = self.retrieve(intent)
        retrieval_span.end(documents=len(context))
        
        # Step 3: Generation
        generation_span = trace.span('generate-response')
        response = self.generate(query, context)
        generation_span.end(tokens=response.usage.total)
        
        trace.complete(output=response.text)
        return response.text

Best Practices

1. Clear Goals

Define specific, measurable goals for your agents

2. Robust Error Handling

Agents should gracefully handle errors and edge cases

3. Human-in-the-Loop

Include human oversight for critical decisions

4. Observability

Monitor agent behavior, decisions, and outcomes

5. Continuous Improvement

Learn from agent interactions and improve over time

Next Steps

OverviewThree Pillars