Agent Responses Quick Start (Terminal Application)

This document uses the scenario of “terminal device capturing images for recognition” as an example to demonstrate how to:

1. Create a terminal device model in the Ticos Cloud platform.
2. Register terminals to be supported.
3. Send images and parse the returned content through the Agent Responses API in a terminal application.

Before reading this guide, please make sure you have registered with Ticos Cloud.

1. Log in to Ticos Cloud

Visit https://cloud.ticos.ai  and log in with your assigned account.

2. Create a Terminal Model

1. Select Settings → Terminal Models → Add Model from the navigation bar.

2. Fill in the following information in the popup:
   • Terminal Type: Select the type that suits your device, such as Camera. If there is no matching type, you can safely select “Other”, which will not affect the actual functionality.
   • Brand / Manufacturer, Model Name, Description: Fill in the actual information.
   • Upload a photo of the terminal model and enable Published.

3. Click Save.

After saving, you will return to the list. Click “Edit Model” to enter the next level interface. The number at the end of the browser address bar is the model ID. Record it for later use when accessing the API.

3. Register Terminal Devices

1. Select Terminal Ops → Terminals → Add Terminal.
2. Fill in the following information:

3. Save and repeat the above process until all terminals are registered.

4. Create an Agent

Before calling the Agent Responses API, you need to create an agent and ensure it uses OpenAI as the model provider.

1. Select Embodied Agents → Create Agent from the navigation bar.
2. Fill in the agent name, description, and other basic information.
3. In the Models tab, make sure to select OpenAI as the model provider.
   • It is recommended to choose a model with vision capabilities (such as GPT-4o) to process image inputs.
4. Enter the desired business logic in the agent’s “Instructions”, for example:
   • Count how many people are in the provided image and return in JSON format {"count": n}.
5. After creation, record the Agent ID (which can be obtained from the browser address bar).

For detailed configuration of agent models, please refer to the Agent Model Configuration documentation.

5. Obtain Terminal Key

1. In the terminal list, click … → View Details in the Actions column.

2. In the popup dialog, click the copy button to the right of Key to obtain the API Key for that terminal.

This key will be used later to upload files and call the API.

6. Call the Agent Responses API

Use the terminal key to call the agent’s Agent Responses API:

curl -X POST "https://api.ticos.ai/v1/agents/<AgentID>/responses" \
  -H "Authorization: Bearer <TerminalKey>" \
  -H "Content-Type: application/json" \
  -d '{
        "input": "https://assets.ticos.ai/picture1.jpg"
      }'

Input Parameter Explanation

The format of the input parameter refers to the OpenAI API Documentation . The specific content to be provided depends on the business requirements defined in the agent. For example, if the agent is configured to count the number of people in an image, an image URL should be provided.

Return Example

After a successful call, the service returns JSON:

{
  "id": "chatcmpl-BD4u9UtDK3gQBRi3SAZ96KRFGpEFO",
  "object": "chat.completion",
  "created": 1742456817,
  "model": "gpt-4o-2024-08-06",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "{\n  \"count\": 1\n}"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 349,
    "completion_tokens": 42,
    "total_tokens": 391
  }
}

The choices[0].message.content string is the JSON data needed for the business, which can be parsed as needed.

7. Common Issues

By completing the above steps, you can quickly integrate the Ticos Agent Responses service into your target terminal’s application.