Skip to main content

​
What is a LoopOS AI Service?

A LoopOS AI Service is a headless interface accessible via API, designed to interact with various LoopOS AI agents. Each service is specialized in a specific operation relevant to the circular economy.

Self-Contained

Each service operates independently with its own agents and tools.

API-First

All services expose REST endpoints for easy integration.

Context-Aware

Services leverage business context and item data for intelligent responses.

Observable

Built-in tracing and monitoring for all service operations.

​
Service Types

​
Conversational Services

Services that maintain conversation state and interact with users:
  • Submission Service: Guides users through product submission with multi-agent workflow
  • Chat Endpoint: General conversational interface for various use cases

​
Single-Purpose Services

Services that perform specific tasks without conversation:
  • Decision Service: Makes choices from options based on context
  • C2C Descriptor: Generates marketplace listings
  • C2C Validation: Validates marketplace content
  • Brands Generator: Finds common brands for categories
  • Value Estimation: Estimates item values
  • ID Validator: Validates ID documents
  • Translator: Translates catalog data
  • Protocol Generator: Generates protocol questions

​
Common Input Structure

All services share a common base input structure: 
interface LoopOsAiServiceInput {
  // Session & Context
  session_id?: string;              // Session identifier
  language?: string;                 // Language code (default: "PT-PT")
  conversation?: boolean;            // Whether this is conversational
  loopos_core_context?: string;      // Business context
  
  // Communication
  messages?: Message[];              // Conversation messages
  images?: string[];                // Image URLs or base64 data
  
  // Service-Specific
  agent_specific?: object;           // Service-specific parameters
  
  // Metadata
  session_extra_data?: object;      // Additional session metadata
  callback_url?: string;            // Async callback URL
  error?: string;                   // Error message for retries
}

​
Message Format

Messages follow a standard format: 
{
  "role": "user",
  "text": "Hello, I want to sell an iPhone"
}
Or with HTML content: 
{
  "role": "assistant",
  "text": "I can help you with that!",
  "html": "<div>...</div>"
}

​
Common Output Structure

Services return structured responses: 
interface LoopOsAiServiceOutput {
  // Agent Response
  agent_specific?: object;          // Service-specific output
  reasoning?: string;               // Explanation of the decision/result
  references?: string[];            // Reference sources used
  
  // Conversation (if conversational)
  messages?: Message[];             // Conversation messages
  
  // Metadata
  session_id?: string;              // Session identifier
  session_extra_data?: object;      // Session metadata
}

​
Service Patterns

​
Pattern 1: Simple Decision Service

Single agent, direct response: 
Request → Agent → Tool Calls → Structured Output → Response
Example: Decision Service

​
Pattern 2: Multi-Agent Workflow

Multiple agents with handoffs: 
Request → Agent 1 → Handoff → Agent 2 → Handoff → Agent 3 → Response
Example: Submission Service

​
Pattern 3: Routing Service

Service routes to different agents based on input: 
Request → Router → Agent A (if condition X)
                → Agent B (if condition Y)
                → Agent C (if condition Z)
Example: C2C Validation Service

​
Service Lifecycle

1

Request Validation

Input validated against Pydantic models, invalid requests rejected with 422.
2

Context Initialization

Service initializes context with request data, business context, and session state.
3

Agent Execution

Starting agent processes input, may call tools, and may hand off to other agents.
4

Response Generation

Agent output formatted into service response structure.
5

Observability

Request traced in Langfuse with tokens, costs, and performance metrics.

​
Error Handling

Services handle errors consistently:

Validation Errors

422: Invalid input parameters, detailed error messages in response.

Size Limits

413: Request exceeds size limits (default: 10MB).

Rate Limiting

429: Too many requests, rate limit exceeded.

Server Errors

500: Internal server error, logged for investigation.

​
Session Management

Sessions track conversation state:
  • Session ID: Unique identifier for the conversation
  • Session State: Stored in database, shared across requests
  • Context Persistence: Previous context available for subsequent requests
  • Session Metadata: Additional data stored with session_extra_data

​
Tool Integration

Services use tools to interact with external systems:

Catalog Tools

Query product catalogs, brands, categories.

Web Search

Search web for market data, pricing, references.

Item Management

Create, update, retrieve items from LoopOS Core.

Validation Tools

Validate data against business rules and catalogs.

​
Best Practices

Use appropriate service types: Use conversational services for user interactions, single-purpose services for automated tasks.
Provide business context: Always include loopos_core_context to help agents understand your business.
Manage sessions: Reuse session_id for conversational services to maintain context.
Handle errors gracefully: Implement retry logic and error handling in your client code.

​
Available Services

Explore the available services: