Skip to main content

​
What is an Agent?

An Agent in LoopOS AI is a specialized AI entity that can:
  • Process natural language input
  • Call tools to interact with external systems
  • Make decisions and generate structured outputs
  • Hand off to other agents when needed
Agents are built using the OpenAI Agents framework and are specialized for specific tasks.

​
Agent Architecture

Each agent has:

Instructions

System instructions that define agent behavior and goals.

Tools

Functions the agent can call to interact with external systems.

Output Type

Pydantic model defining the structured output format.

Handoffs

Other agents this agent can hand off to with conditions.

​
Agent Types

​
Single-Purpose Agents

Agents that perform one specific task:
  • Decision Agent: Chooses from options based on context
  • Brands Agent: Finds common brands for categories
  • Value Estimation Agent: Estimates item values
  • ID Validator Agent: Validates ID documents

​
Workflow Agents

Agents that are part of multi-step workflows:
  • Product Identification Agent: Identifies products from catalog
  • Product Options Agent: Collects product options/variants
  • Create Item Agent: Creates items in LoopOS Core
  • Protocol Agent: Asks and validates protocol questions

​
Validation Agents

Specialized agents for validation tasks:
  • Title/Description Validation Agent: Validates marketplace listings
  • Brand Validation Agent: Validates brand names
  • Product Validation Agent: Validates product names

​
Agent Handoffs

Agents can hand off to other agents when specific conditions are met: 
# Example: Product Identification → Options → Create Item → Protocol
loop_os_ai_submission_product_identification_agent
    ↓ (handoff when product confirmed)
loop_os_ai_submission_product_options_agent
    ↓ (handoff when options selected)
loop_os_ai_submission_create_item_agent
    ↓ (handoff when item created)
loop_os_ai_submission_protocol_agent

​
Handoff Conditions

Handoffs occur when:
  • Agent calls a specific tool (e.g., create_item)
  • Agent generates specific output (e.g., product_id in context)
  • User provides specific input (e.g., confirms product selection)

​
Handoff Data

Data passed between agents: 
class ProductIdentificationData(BaseModel):
    product_id: str
    brand_id: str
    # ... other fields

​
Tools

Tools are functions agents can call to interact with external systems:

Catalog Tools

get_catalog: Query products, brands, categories

Item Tools

create_item: Create items in LoopOS Core

Protocol Tools

get_product_protocol: Get protocol questions validate_protocol_answer: Validate answers

Web Search

web_search: Search web for market data

​
Tool Execution

Tools are executed by agents during conversation:
  1. Agent decides to call a tool based on instructions
  2. Tool function executes (may call external APIs)
  3. Tool result returned to agent
  4. Agent processes result and continues conversation

​
Agent Context

Agents maintain context throughout execution: 
class LoopOsAiSubmissionAgentContext(BaseModel):
    # Item data
    product_id: Optional[int] = None
    brand_id: Optional[int] = None
    option_value_ids: List[int] = []
    item_token: Optional[str] = None
    item_id: Optional[int] = None
    
    # LoopOS Core connection
    loopos_core_base_url: str
    loopos_core_api_block: str
    
    # Business context
    loopos_core_context: Optional[str] = None
Context flows through the agent system:
  • Initialized from request
  • Updated by tools
  • Passed to handoffs
  • Used in final output

​
Agent Instructions

Instructions define agent behavior: 
agent.instructions = f'''
You are the Product Identification Agent.
Your goal is to identify the product from the user's description.

TOOL EXECUTION POLICY:
1. Always call 'get_catalog' to search for products
2. Present options to user for confirmation
3. Hand off to options agent when product confirmed
'''
Key instruction patterns:
  • Role definition: What the agent is
  • Goal: What the agent should accomplish
  • Tool policies: When and how to use tools
  • Handoff conditions: When to hand off to other agents
  • Communication style: How to interact with users

​
Output Types

Agents return structured outputs defined by Pydantic models: 
class LoopOsAiSubmissionOutput(BaseModel):
    text: str
    role: str = "assistant"
    html: Optional[str] = None
    # ... other fields
Outputs are validated and can include:
  • Text responses
  • HTML content
  • Structured data
  • Tool call results

​
Multi-Agent Workflows

Complex workflows use multiple agents:

​
Submission Workflow

1

Product Identification

User describes product → Agent searches catalog → Presents options → User confirms
2

Options Selection

Agent presents product options → User selects → Options validated
3

Item Creation

Agent creates item in LoopOS Core → Receives item_token
4

Protocol Questions

Agent asks protocol questions → Validates answers → Completes submission

​
Best Practices

Clear instructions: Write clear, specific instructions for agents to follow.
Tool design: Design tools to be atomic and focused on single tasks.
Handoff conditions: Make handoff conditions explicit and testable.
Context management: Keep context models focused and avoid unnecessary fields.