Scenarios
When an enterprise uses multiple Agent platforms simultaneously, each platform is independently deployed and exposes its own HTTP API. The business side then needs to connect to different addresses and authentication methods for each, resulting in high management costs and a lack of unified auditing. By using the AI Gateway Agent API, you can unify all Agent services into a single entry point, enabling:
Unified Access for Multi-Source Agents: Agent services from different platforms (Coze / Dify / self-built TCAR / MCP Server) are routed to their corresponding backends based on routing rules. Your business system only needs to connect to a single gateway entry point.
Protocol-Agnostic Transparent Proxy: It does not rely on any specific vendor protocol. Any backend service that supports HTTP/S can be connected, without the need to adapt SDKs or modify existing Agents.
Unified Governance and Observability: All Agent requests are uniformly authenticated, rate-limited, and audited by the gateway, and the entire invocation chain is fully traceable.
Prerequisites
The AI Gateway instance has been created.
The backend service has been created (configured in Service Management > Services).
Operation Steps
Creating an Agent API
Step 1: Go to the Agent API List Page
2. Click the ID/Name of the target instance to go to its details page and access the target gateway instance.
3. In the left sidebar, select Agent Management.
4. On the Agent API tab, click New.
Step 2: Configure Basic Information
In the pop-up creation window, configure the following information:
|
API Name | Yes | The unique identifier for the Agent API, supporting English letters, numbers, underscores, and hyphens, with a length of 1-64 characters. | agent-backend-api
|
Request protocol | Yes | Custom (different from the OpenAI-compatible protocol for model APIs) Dify A2A | Custom
|
Backend Agent service | Required if Dify or A2A is selected as the request protocol. | Select the corresponding type of Agent service from the dropdown list. You can click to jump to the New Consumer page. | - |
Base Path | Yes | The path prefix for the API. All route paths use this as their prefix. If you set the Base Path to /agent and create a route path as /api/users, the client access address will be: https://{gateway-domain}/agent/api/users. | /agent
|
Description | No | Custom description information | xx feature
|
Step 3: Complete the Creation
After confirming the configuration is correct, click OK to complete the Agent API creation. Upon successful creation, the system automatically redirects to the Agent API details page.
Managing Agent APIs
Viewing Agent API List
On the Agent Management > Agent API list page, you can view all created Agent APIs:
Viewing Agent API Details
Click the API name to go to its details page and view the API's basic information.
Editing an Agent API
1. On the Agent API list page, click Edit in the Actions column.
2. Modify the basic API information. Note: The API name cannot be changed after creation.
3. Click OK to save the modifications.
Deleting an Agent API
1. On the Agent API list page, click Delete in the Actions column.
2. In the pop-up confirmation dialog box, click OK.
Attention:
After an Agent API is deleted, all requests under that API cannot be routed. Proceed with caution.
Before deletion, a resource dependency check must be passed. If unresolved dependencies exist, such as associated routes, deletion is not allowed.
Creates a routing rule
An Agent API distributes requests to different backend services based on routing rules. A single Agent API can have multiple routing rules.
Step 1: Go to the Routing List
1. On the Agent API details page, select the Routing List Tab.
2. Click New.
Step 2: Configure Basic Information
Basic Information
|
Route Name | No | The name of the route, which supports Chinese, English, numbers, ., -, and _. | User service route
|
Request protocol | Yes | Select the supported protocol. The default is "HTTP&HTTPS". | HTTP&HTTPS
|
Matching Rules
Note:
You must configure at least one of the following: request method, request path, or Host. Headers are optional. For details, see Route Matching Instructions. |
Request Method | At least one must be configured. | Supported HTTP methods, multiple selections allowed | GET,POST
|
Request path |
| Path matching rules, supporting exact matching, prefix matching, and regular expression matching. | Prefix matching: /api/users |
Host |
| Matches hostnames. Supports case-sensitive configuration. Multiple entries can be added. | api.example.com
|
Header | No | Matches request headers. Keys support digits, letters, _, and -. Multiple entries can be added. | X-Service: user-service
|
Advanced Configuration (Optional)
You can select to enable/disable Strip Path based on your actual requirements.
Enable: When forwarding requests to the backend, the gateway strips the prefix used for route matching from the request path and passes only the remaining path to the backend service. This is suitable for scenarios where the backend API does not contain that prefix.
Disable: The gateway forwards the complete original path of the user request unchanged to the backend service. This is suitable for scenarios where the backend API already contains that prefix.
Step 3: Configure the Routing Backend
In the second step, configure the backend service for the route by selecting it from the "Service Management > Services" list.
Step 4: Complete the Creation
Click Finish Creation. The routing rule is created successfully.
Editing and Deleting Routing
Edit Routing
1. On the Agent API details page > Routing List Tab, choose the route you want to edit.
2. Click the Edit Route button in the route details area on the right.
3. Modify the route configuration using a two-step wizard, which is the same as the creation process.
4. Click OK to save the modifications.
Delete Routing
1. On the Agent API details page > Routing List Tab, choose the route you want to delete.
2. Click More Actions > Delete in the route details area on the right.
3. In the confirmation dialog box, click OK.
Attention:
After you delete a route, all requests for that route will become unroutable. Proceed with caution.
Viewing Routing Details
On the Agent API details page > Routing List Tab, after you choose a route from the route list on the left, the route details are displayed on the. right.