Skip to main content

​
Overview

The Submission Service is a conversational AI agent that enables users to submit used items through natural language and photos. It guides users through:
  1. Product Identification: Finding the product in the catalog
  2. Options Selection: Choosing product variants/options
  3. Item Creation: Creating the item in LoopOS Core
  4. Protocol Completion: Answering all required protocol questions
This is the only service that doesn’t follow the standard LoopOS AI services pattern. It uses the /chat endpoint and follows the DeepChat standard for conversational interfaces.

​
How It Works

The Submission Service uses a multi-agent workflow:
1

Product Identification

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

Options Selection

Agent presents product options/variants → User selects → Options validated
3

Item Creation

Agent creates item in LoopOS Core → Receives item_token and item_id
4

Protocol Questions

Agent asks all protocol questions → Validates answers → Completes submission

​
Agents

​
Product Identification Agent

Identifies products from user descriptions and images:
  • Tools: get_catalog - Searches catalog for products
  • Behavior:
    • Always validates against catalog (never invents products)
    • Presents options when multiple matches found
    • Uses images to help identify products
    • Confirms product and brand before proceeding

​
Product Options Agent

Collects product options/variants:
  • Tools: get_product_options - Retrieves available options
  • Behavior:
    • Presents options as buttons
    • Validates selections
    • Handles “See more” for long option lists

​
Create Item Agent

Creates the item in LoopOS Core:
  • Tools: create_item - Creates item via LoopOS Core API
  • Behavior:
    • Requires product_id, brand_id, option_value_ids
    • Creates item and receives item_token
    • Immediately hands off to protocol agent

​
Protocol Agent

Asks and validates protocol questions:
  • Tools:
    • get_product_protocol - Gets protocol questions
    • validate_protocol_answer - Validates answers
    • finish_product_creation - Completes submission
  • Behavior:
    • Asks one question at a time
    • Shows progress (e.g., “1/10”)
    • Uses images to infer answers when possible
    • Presents final summary before completion

​
API Endpoint

POST /chat Follows the DeepChat standard for conversational interfaces.

​
Request Format

{
  "language": "PT-PT",
  "messages": [
    {"role": "user", "text": "Quero vender um iPhone 12"}
  ],
  "images": [],
  "conversation": true,
  "session_id": "my-session-123",
  "loopos_core_context": "Circular economy marketplace",
  "loopos_core_base_url": "https://core.decs.stg.loopos.app/",
  "loopos_submission_base_url": "https://submission.decs.stg.loopos.app/"
}

​
Response Format

[
  {
    "text": "Ótimo! Vou ajudar-te a submeter o teu iPhone 12.",
    "role": "assistant",
    "html": "<div>...</div>"
  }
]

​
Request Parameters

FieldTypeRequiredDescription
languagestringNoLanguage code (default: “PT-PT”)
messagesarrayYesConversation messages
imagesarrayNoImage URLs or base64 data
conversationbooleanNoWhether this is conversational (default: true)
session_idstringNoSession identifier for conversation tracking
loopos_core_contextstringNoBusiness context
loopos_core_base_urlstringYesLoopOS Core base URL
loopos_submission_base_urlstringYesLoopOS Submission base URL
loopos_submission_tag_filterstringNoTag filter for submission
loopos_submission_product_tag_filterstringNoProduct tag filter
loopos_submission_category_tag_filterstringNoCategory tag filter
loopos_submission_brand_tag_filterstringNoBrand tag filter

​
Integration with LoopOS Core

The Submission Service requires a LoopOS Core script block:

​
Required Script Block

  • Name: LoopOSAISubmissionAPI
  • Slug: loopos_ai_submission_api
  • Location: LoopOS Flow Script Block
The script provides endpoints for:
  • Catalog queries
  • Product options retrieval
  • Protocol questions
  • Item creation
  • Protocol answer validation

​
Features

Image Support

Users can upload images to help identify products and answer protocol questions.

Catalog Validation

All product suggestions validated against catalog - never invents products.

Progress Tracking

Shows progress through protocol questions (e.g., “1/10”).

Answer Validation

All protocol answers validated before acceptance.

Button Options

Options presented as clickable buttons for better UX.

Final Summary

Presents final summary before completion for user confirmation.

​
Protocol Question Flow

The Protocol Agent follows a specific flow:
  1. Get Protocol: Calls get_product_protocol to retrieve all questions
  2. Iterate Questions: Asks each question one at a time
  3. Show Progress: Displays question number (e.g., “1/10”)
  4. Present Options: Shows options as buttons when available
  5. Validate Answers: Validates each answer before accepting
  6. Final Summary: Presents complete summary before submission
  7. Complete: Calls finish_product_creation to finalize

​
Best Practices

Reuse session_id: Maintain conversation context by reusing the same session_id across requests.
Provide context: Include loopos_core_context to help agents understand your business.
Handle images: Support image uploads to improve product identification and protocol answers.
Error handling: Implement retry logic for failed tool calls or network issues.

​
Limitations

Image protocol elements are excluded from the conversational flow. Users must complete image protocol elements in the standard submission form.
The service requires the LoopOS Core script block to be properly configured. Ensure the script is activated and accessible.

​
Example Conversation

User: "Quero vender um iPhone 12"

Agent: "Ótimo! Vou ajudar-te a submeter o teu iPhone 12. 
        Deixa-me procurar no catálogo..."

[Agent searches catalog]

Agent: "Encontrei o iPhone 12 no catálogo. Qual é a marca?
        [Apple] [Samsung] [Outra]"

User: "Apple"

Agent: "Perfeito! iPhone 12 da Apple. Agora preciso de algumas 
        informações sobre o estado do artigo.
        
        1/5. Qual é o estado do artigo?
        [Excelente] [Muito Bom] [Bom] [Razoável]"

[... continues with protocol questions ...]

Agent: "Excelente! Recolhi todas as informações. Aqui está o resumo:
        - Produto: iPhone 12
        - Marca: Apple
        - Estado: Bom
        - ...
        
        [Confirmar] [Alterar]"