数据库启动命令： docker pull docker.1ms.run/library/postgres:latest docker run --name postgres -e POSTGRES_PASSWORD=1qaz@WSX -p 5432:5432 -d docker.1ms.run/library/postgres:latest

前端启动： docker run -p 8000:8000 -it docker.cnb.cool/aubreycyp/adp-chat-client:latest

ADP-Chat-Client is an open sourced AI Agent application conversation interface. It allows developers to quickly deploy AI agent applications developed on the Tencent Cloud Agent Development Platform (Tencent Cloud ADP) as web applications (or embed them into mini-programs, Android, and iOS apps). The client supports real-time conversations, conversation history management, voice input, image understanding, third-party account system integration, and more. It supports fast deployment via Docker.

• Deployment
• Development Guide
  • Backend
  • Frontend
• Advanced Topics
  • Variables - API Parameters

Please ensure the machine meets the minimum requirements:

• CPU >= 2 Core
• RAM >= 4 GiB
• Operating System: Linux/macOS. If you want to run on Windows, you need to use WSL or a cloud server with a Linux system.

1. Clone the source code and enter the project directory.

git clone https://github.com/TencentCloudADP/adp-chat-client.git
cd adp-chat-client

2. Install docker (skip if docker is already installed on your system):

For TencentOS Server 4.4:

bash script/init_env_tencentos.sh

For Ubuntu Server 24.04:

bash script/init_env_ubuntu.sh

3. Copy the .env.example file to the deploy folder:

cp server/.env.example deploy/default/.env

4. Edit the deploy/default/.env file:

You need to fill in the following credentials and application keys based on your Tencent Cloud account and ADP platform information:

# Tencent Cloud account secret: https://console.tencentcloud.com/cam/capi
TC_SECRET_APPID=
TC_SECRET_ID=
TC_SECRET_KEY=
# Tencent Cloud ADP platform agent app key: https://adp.tencentcloud.com/
APP_CONFIGS='[
    {
        "Vendor":"Tencent",
        "ApplicationId":"The unique ID of the chat application, used to uniquely identify a chat application in this system. Recommended to use appid or generate a random uuid using the uuidgen command",
        "Comment": "Comment",
        "AppKey": "",
        "International": true
    }
]'

# JWT secret key, a random string, can be generated using the uuidgen command
SECRET_KEY=

⚠️ Note:

1. The content of APP_CONFIGS is in JSON format. Please adhere to JSON specifications, e.g., the last item should not end with a comma, and // comments are not supported.
2. Comment: Can be filled in freely for easy identification of the corresponding agent application.
3. International: If the agent application is developed on the ADP, set the value to true.
4. ApplicationId: Access any ADP application and check the appid in the application URL. For example, if an application's link is https://adp.tencentcloud.com/adp/#/app/knowledge/app-config?appid=197******768&appType=knowledge_qa&spaceId=default_space, then its ApplicationId is 197******768.
5. Vendor: Fixed to "Tencent", other options may be available for other platforms in the future.

5. Build docker image

# Build image (The initial deployment requires packing, and it needs to be rerun after code changes, no need to repack if you only modify the .env file).
sudo make pack

6. Start the container

sudo make deploy

Open the browser and navigate to http://localhost:8000 to view the login page.

⚠️ Warning: For production environment, you need to apply for an SSL certificate through your own domain and deploy it over HTTPS using nginx for reverse proxy or other methods. If deployed over HTTP, certain features (such as voice recognition, message copying, etc.) may not function properly.

7. Login

This system supports integration with existing account systems. Here, we demonstrate the URL Redirection login method:

sudo make url

The above command retrieves the login URL. Open this URL in the browser for login.

If OAuth login is configured, you can log in by opening http://localhost:8000 in the browser.

8. Troubleshooting

# Check if the containers are running. Normally, there should be 2 containers: adp-chat-client-default, adp-chat-client-db-default
sudo docker ps

# If no containers are visible, it indicates a startup issue. You can check the logs:
sudo make logs

📺 Video Tutorial

To use the system, enable/configure the following services:

1. Dialogue title generation: Tencent Cloud DeepSeek OpenAI API.
2. Voice input: Speech Recognition: Settings, enable: Real-time speech recognition for the required region.
3. App Permission: Make sure the account associated with your TC_SECRET_ID/TC_SECRET_KEY has permission to access the applications you’ve added. For details, see the platform-side user permissions documentation.

GitHub OAuth is supported by default. You can can configure it as needed:

# you can obtain it from https://github.com/settings/developers
OAUTH_GITHUB_CLIENT_ID=
OAUTH_GITHUB_SECRET=

📝 Note：When creating a GitHub OAuth application, fill in the callback URL as：SERVICE_API_URL+/oauth/callback/github, for example: http://localhost:8000/oauth/callback/github

Microsoft Entra ID OAuth is supported by default. You can can configure it as needed:

# you can obtain it from https://entra.microsoft.com
OAUTH_MICROSOFT_ENTRA_CLIENT_ID=
OAUTH_MICROSOFT_ENTRA_SECRET=

📝 Note：When creating a Microsoft Entra ID OAuth application, fill in the callback URL as：SERVICE_API_URL+/oauth/callback/ms_entra_id, for example: http://localhost:8000/oauth/callback/ms_entra_id

OAuth protocol enables seamless authentication and authorization. Developers can customize authentication methods according to their requirements. If you need to use a different OAuth system, you can modify the server/core/oauth.py file to adapt to the specific protocol.

If you have an existing account system but do not implement a standard OAuth flow, you can integrate with the system using a URL redirect method for simpler integration.

1. Your account service: Generate a URL pointing to this system, carrying CustomerId, Name, Timestamp, ExtraInfo, Code, etc.
2. User: Clicks the URL to login to their account.
3. This system: Verifies the signature, auto-creates/binds the account, generates a login session, and redirects to the chat page.

Parameter	Description
url	https://your-domain.com/account/customer?CustomerId=&Name=&Timestamp=&ExtraInfo=&Code=
CustomerId	Your account system's uid
Name	Your account system's username (optional)
Timestamp	Current timestamp
ExtraInfo	User information
Code	Signature, SHA256(HMAC(CUSTOMER_ACCOUNT_SECRET_KEY, CustomerId + Name + ExtraInfo + str(Timestamp)))

📝 Note:

1. The parameters above must be URL-encoded, for more details you can refer to the CoreAccount.customer_auth in server/core/account.py file, and generate_customer_account_url in server/main.py file for URL generation method.
2. Configure CUSTOMER_ACCOUNT_SECRET_KEY in the .env file, a random string that can be generated using the uuidgen command.

• python >= 3.12
• uv ~= 0.8

# 1. Execute all the steps in [Deployment] section
# 2. Copy the edited .env file to the server folder
cp deploy/default/.env server/.env

# 3. Initialize (only needed on the first run)
make init_server

# 4. continue to [Frontend] section below.

• node >= 20

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc
nvm install v22

# Initialize (only needed on the first run)
make init_client

# Run the backend/frontend in dev mode, the terminal will print the debugging URL, such as: [ui]   ➜  Local:   http://localhost:5173/
make dev

Component	Description
config	Configuration system
core	Core logic, not bound to specific protocols (e.g., HTTP or stdio)
middleware	Middleware for the Sanic server
model	ORM definitions for entities, e.g., Account
router	Externally exposed HTTP endpoints, typically wrapping core logic
static	Static files
test	Testing
util	Other utility classes

When calling the agent for conversation, you can pass parameters to the agent. Depending on the specific situation, you can choose to pass them on the frontend or backend. Here is an example of adding API parameters on the backend:

# Edit file: server/router/chat.py
class ChatMessageApi(HTTPMethodView):
    @login_required
    async def post(self, request: Request):
        parser = reqparse.RequestParser()
        parser.add_argument("Query", type=str, required=True, location="json")
        parser.add_argument("ConversationId", type=str, location="json")
        parser.add_argument("ApplicationId", type=str, location="json")
        parser.add_argument("SearchNetwork", type=bool, default=True, location="json")
        parser.add_argument("CustomVariables", type=dict, default={}, location="json")
        args = parser.parse_args(request)
        logging.info(f"ChatMessageApi: {args}")

        application_id = args['ApplicationId']
        vendor_app = app.get_vendor_app(application_id)

        # Add the following code to attach additional API parameters during conversation:
        from core.account import CoreAccount
        account = await CoreAccount.get(request.ctx.db, request.ctx.account_id)
        # Note the json.dumps here: Tencent Cloud ADP convention requires that if the value is a dictionary, it needs to be JSON-encoded once and converted to a JSON string
        args['CustomVariables']['account'] = json.dumps({
            "id": str(account.Id),
            "name": account.Name,
        })
        logging.info(f"[ChatMessageApi] ApplicationId: {application_id},\n\
            CustomVariables: {args['CustomVariables']},\n\
            vendor_app: {vendor_app}")