Agent Responses Quick Start (Server-side 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 server-side application.

Before reading this guide, please make sure you have completed account registration and obtained an API Key.

1. Log in to the Platform

Visit https://cloud.ticos.ai  and log in with your 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 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. Call the Agent Responses API

The following example demonstrates how to call the API using curl and pass terminal model ID, terminal ID, and other information in the request headers.

curl -X POST "https://api.ticos.ai/v1/agents/<AgentID>/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <Your-API-Key>" \
  -H "X-Model-ID: <ModelID>" \
  -H "X-Client-Identifier: <TerminalID>" \
  -d '{
        "input": "http://<your-domain>/path/to/image.jpeg"
      }'

Placeholder explanations:

The API-Key is shown below. You can copy an existing API key or create a new one from User Menu -> API Keys.

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.

6. Common Issues

By completing the above steps, you can quickly integrate the Ticos Agent Responses service into your required server-side application scenarios.