agentscope-ai Higress AI Gateway Management
Overview
This skill allows you to manage the Higress AI Gateway via its Console API. The Console API runs at http://127.0.0.1:8001 and uses Session Cookie authentication (NOT Basic Auth).
Environment Variables
These environment variables are pre-configured in the Manager container. Access them directly in bash:
# Core configuration (set by agentteams-install.sh)
AGENTTEAMS_ADMIN_USER # Admin username for Higress Console
AGENTTEAMS_ADMIN_PASSWORD # Admin password for Higress Console
AGENTTEAMS_AI_GATEWAY_DOMAIN # AI Gateway domain (e.g., aigw-local.agentteams.io)
HIGRESS_COOKIE_FILE # Path to session cookie file
No need to set defaults - these are always available in the container environment.
Authentication
A session cookie file is stored at the path in ${HIGRESS_COOKIE_FILE} environment variable. Use it with curl -b "${HIGRESS_COOKIE_FILE}".
If the cookie expires, re-login:
curl -X POST http://127.0.0.1:8001/session/login \
-H 'Content-Type: application/json' \
-c "${HIGRESS_COOKIE_FILE}" \
-d '{"name": "'"${AGENTTEAMS_ADMIN_USER}"'", "password": "'"${AGENTTEAMS_ADMIN_PASSWORD}"'"}'
Consumer Management
List Consumers
curl -s http://127.0.0.1:8001/v1/consumers -b "${HIGRESS_COOKIE_FILE}" | jq
Create Consumer
curl -X POST http://127.0.0.1:8001/v1/consumers \
-b "${HIGRESS_COOKIE_FILE}" \
-H 'Content-Type: application/json' \
-d '{
"name": "worker-alice",
"credentials": [{
"type": "key-auth",
"source": "BEARER",
"values": ["<GENERATED_KEY>"]
}]
}'
Update Consumer (e.g., replace credential key)
# GET-modify-PUT pattern (consumers do NOT have a version field)
NEW_KEY=$(openssl rand -hex 32)
CONSUMER=$(curl -s http://127.0.0.1:8001/v1/consumers/worker-alice -b "${HIGRESS_COOKIE_FILE}")
UPDATED=$(echo $CONSUMER | jq --arg new "$NEW_KEY" '.credentials[0].values = [$new]')
curl -X PUT http://127.0.0.1:8001/v1/consumers/worker-alice \
-b "${HIGRESS_COOKIE_FILE}" \
-H 'Content-Type: application/json' \
-d "$UPDATED"
Delete Consumer
curl -X DELETE http://127.0.0.1:8001/v1/consumers/worker-alice -b "${HIGRESS_COOKIE_FILE}"
AI Route Management
AI routes are internal routes managed via a separate API at /v1/ai/routes. They define LLM provider routing with model-level predicates, domain matching, and consumer auth. Do NOT use /v1/routes for AI routes.
List AI Routes
curl -s http://127.0.0.1:8001/v1/ai/routes -b "${HIGRESS_COOKIE_FILE}" | jq
Get AI Route by Name
curl -s http://127.0.0.1:8001/v1/ai/routes/default-ai-route -b "${HIGRESS_COOKIE_FILE}" | jq
Create AI Route
The system initializes with a default-ai-route that has no modelPredicates — all model requests go through it. When the human asks to add a new provider, create a separate AI route with modelPredicates to distinguish which models go where:
# Example: add a DeepSeek route alongside the existing default route
curl -X POST http://127.0.0.1:8001/v1/ai/routes \
-b "${HIGRESS_COOKIE_FILE}" \
-H 'Content-Type: application/json' \
-d '{
"name": "deepseek-route",
"domains": ["${AGENTTEAMS_AI_GATEWAY_DOMAIN}"],
"pathPredicate": {"matchType": "PRE", "matchValue": "/", "caseSensitive": false},
"upstreams": [{"provider": "deepseek", "weight": 100, "modelMapping": {}}],
"modelPredicates": [{"matchType": "PRE", "matchValue": "deepseek"}],
"authConfig": {
"enabled": true,
"allowedCredentialTypes": ["key-auth"],
"allowedConsumers": ["manager"]
}
}'
When adding a new provider route with modelPredicates, also update the default-ai-route to add matching modelPredicates for its own models, so routes are unambiguous.
Key fields:
- domains: which domain(s) this AI route serves (e.g.
${AGENTTEAMS_AI_GATEWAY_DOMAIN}) - upstreams: LLM provider(s) with weight and optional model mapping
- modelPredicates: match models by prefix/exact/regex (e.g.
{"matchType":"PRE","matchValue":"deepseek"}routes alldeepseek*models). Omit when only one route exists - authConfig: consumer-level access control
Update AI Route (e.g., grant Worker access)
# Step 1: GET current AI route
AI_ROUTE=$(curl -s http://127.0.0.1:8001/v1/ai/routes/default-ai-route -b "${HIGRESS_COOKIE_FILE}")
# Step 2: Add worker-alice to allowedConsumers
UPDATED=$(echo $AI_ROUTE | jq '.authConfig.allowedConsumers += ["worker-alice"]')
# Step 3: PUT full object (AI Route has "version" field, include it)
curl -X PUT http://127.0.0.1:8001/v1/ai/routes/default-ai-route \
-b "${HIGRESS_COOKIE_FILE}" \
-H 'Content-Type: application/json' \
-d "$UPDATED"
Delete AI Route
curl -X DELETE http://127.0.0.1:8001/v1/ai/routes/<route-name> -b "${HIGRESS_COOKIE_FILE}"
LLM Provider Configuration
List AI Providers
curl -s http://127.0.0.1:8001/v1/ai/providers -b "${HIGRESS_COOKIE_FILE}" | jq
Create Provider
# Qwen (native type)
curl -X POST http://127.0.0.1:8001/v1/ai/providers \
-b "${HIGRESS_COOKIE_FILE}" \
-H 'Content-Type: application/json' \
-d '{
"type": "qwen", "name": "qwen",
"tokens": ["<API_KEY>"], "protocol": "openai/v1",
"tokenFailoverConfig": {"enabled": false},
"rawConfigs": {"qwenEnableSearch": false, "qwenEnableCompatible": true, "qwenFileIds": []}
}'
# OpenAI-compatible (generic)
curl -X POST http://127.0.0.1:8001/v1/ai/providers \
-b "${HIGRESS_COOKIE_FILE}" \
-H 'Content-Type: application/json' \
-d '{
"type": "openai", "name": "my-provider",
"tokens": ["<API_KEY>"], "protocol": "openai/v1",
"modelMapping": {},
"rawConfigs": {"apiUrl": "https://api.example.com/v1"}
}'
Update Provider (e.g., rotate API keys)
# GET-modify-PUT pattern (provider has "version" field)
PROVIDER=$(curl -s http://127.0.0.1:8001/v1/ai/providers/qwen -b "${HIGRESS_COOKIE_FILE}")
UPDATED=$(echo $PROVIDER | jq '.tokens = ["<NEW_KEY>"]')
curl -X PUT http://127.0.0.1:8001/v1/ai/providers/qwen \
-b "${HIGRESS_COOKIE_FILE}" \
-H 'Content-Type: application/json' \
-d "$UPDATED"
MCP Server Management
For creating, updating, listing, and deleting MCP Servers, as well as managing consumer access to MCP tools, see the mcp-server-management skill.
Important Notes
- Auth Plugin Activation: First configuration takes ~40s, subsequent changes ~10s
- Version field: AI Routes and Providers have a
versionfield. Always GET before PUT to get the latest version. - Consumer version: Consumers do NOT have a
versionfield - MCP Server: See
mcp-server-managementskill for full details on creating and managing MCP servers