Scenarios
An Agent Service is a resource object in the AI Gateway that describes backend Agent instances. It is used to register the access address, protocol capabilities, and invocation parameters of an Agent. An Agent Service serves as a container for credentials and capabilities and does not expose an access endpoint itself. The external endpoint is provided by the Agent API. To access a backend Agent through the gateway, you must first create an Agent Service and then create an Agent API bound to that Agent Service.
The AI Gateway currently supports two types of Agent providers:
A2A: An agent that follows the A2A (Agent-to-Agent) open protocol. The gateway automatically exposes the AgentCard discovery capability and performs protocol conversion based on the protocol version and transport binding that you declare on the Agent Service.
Dify: Proxies applications hosted on the Dify platform and supports four application types: Chatbot, Agent, Workflow, and Completion.
Prerequisites
An AI Gateway instance has been created, and its status is Running.
The gateway version must be 3.9.5 or later.
You have obtained the accessible URL of the backend Agent (http/https).
Before creating an A2A Agent Service, if you need to declare Skills, you must have already created the corresponding Skills in AI Capability Marketplace > Skill Management.
Before creating a Dify Agent Service, you must have obtained the API key of the Dify application or created the corresponding key in Key Management.
Operation Steps
Creating an Agent Service
2. In the left sidebar, choose Instance List, and click the target AI Gateway instance ID to go to the instance details page.
3. Choose the Agent Management > Agent Service tab and click New.
4. In the New Agent Service dialog, configure the basic information:
|
Service Name | Required | 2-60 characters | Must be unique within the same gateway instance. It cannot be modified after creation. |
Service Platform | Required | A2A / Dify | It cannot be modified after creation. If you select a different provider, the protocol parameters displayed below will differ. |
Timeout Time | Optional. | 1000 to 600000 ms, default 60000 | Timeout for the gateway to request the backend Agent. |
Number of retries | Optional. | 0 to 10, default 5 | Number of retries after the gateway fails to request the backend Agent. |
Description | Optional. | Up to 200 characters | - |
If Provider is set to A2A, continue to configure the A2A protocol parameters:
|
Service Address | Required | Up to 512 characters, must be a valid http/https address. | Access address of the backend Agent, for example, https://a2a.example.com/v1. |
Agent version. | Required | Up to 32 characters | Business version number of the current Agent, which will be written to the externally exposed AgentCard. |
Protocol Version | Required | 0.3 / 1.0
| A2A protocol version followed by the backend Agent. |
Protocol Binding Type | Required | JSONRPC / HTTP+JSON
| Transport layer binding method of the A2A protocol. JSONRPC is based on JSON-RPC 2.0 over HTTP POST, with streaming responses returned through SSE; HTTP+JSON is a RESTful HTTP API, with streaming responses also returned through SSE. |
Supported Capability | Optional. | Streaming output/Push notification
| Declares the A2A protocol capabilities supported by the backend Agent and writes them to the capabilities field of the AgentCard. |
Mount Skill | Optional. | Up to 50 | Select from the Skills already created in the current gateway instance as the Skill list declared by the Agent. The selected Skills must exist in the current gateway instance; otherwise, the creation fails. |
If Provider is set to Dify, continue to configure the Dify parameters:
|
API Address | Required | Up to 512 characters, must be a valid http/https address. | agent access address. Must be a valid API address starting with http:// or https://. |
Application Type | Required | Chatbot / Agent / Workflow / Completion
| Corresponds to the application type on the Dify platform. It cannot be modified after creation. |
API Key Source | Required | Reference a secret / Enter manually | You must select exactly one of the two options. |
API Key | Required when credential method is "manual input". | Enter manually, up to 512 characters. | API key of the Dify application. |
Key | Required when credential method is "reference key". | Select from the secret list. | Must be a key whose vendor is Dify and whose resource type is Agent. |
5. Click OK to complete the creation. The new Agent Service appears in the list, where you can view its ID, provider, URL, and the number of associated Agent APIs.
Viewing Agent Service Details
1. In the Agent Service list, click the target Agent Service name to go to the details page.
2. The details page displays the basic information and protocol information:
Basic information: Agent Service ID, name, provider, URL, description, timeout, number of retries, and creation/modification time.
Service information: service type, service protocol, service address/port, and service path.
Editing an Agent Service
1. In the Agent Service list, find the target Agent Service and click Edit in the operation column.
2. Modify the required parameters and click OK.
Note:
The service name, service platform, and application type (if Dify is selected) cannot be modified. To change them, delete the service and create a new one.
This Agent Service cannot be modified when it is bound to any Agent API. Unbind the Agent API first (or delete the corresponding Agent API) before making modifications.
Deleting an Agent Service
1. In the Agent Service list, find the target Agent Service and click Delete in the operation column.
2. In the confirmation dialog, click OK.
Note:
This Agent Service cannot be deleted when it is bound to any Agent API. The system will display a list of associated resources. Delete or unbind the corresponding Agent API first.
When an Agent Service from the Dify provider is deleted, its associated API keys are not automatically deleted. If they are no longer needed, manually clean them up in API Key Management.
Related Instructions
Collaboration Between A2A Agent Services and Agent APIs
An Agent Service and an Agent API can be bound only when their protocols are consistent:
|
External entry | Agent API(Protocol = A2A) | BasePath, Skill enablement status, and bound Agent service |
Backend registration | Agent service (Provider = A2A) | URL, protocol version, transport binding, capability declaration, associated Skill, timeout and retry |
Key Constraints:
An Agent API with the A2A protocol can only be bound to an Agent Service from the A2A provider, and vice versa. Cross-provider binding is rejected.
After an Agent API is bound to an Agent Service, the bound Agent Service cannot be changed.
When an Agent API is created, a snapshot is taken from the Skill list of the bound Agent Service. Subsequently, on the Agent API, you can only toggle the enable/disable state of individual Skills, and cannot add or remove Skills. To adjust the Skill scope, modify the associated Skills on the Agent Service.
An Agent API with the A2A protocol does not support adding, deleting, or modifying custom routes. Its access endpoint is automatically created and maintained by the system based on the BasePath. If you need custom routing capabilities, use an Agent API with the Custom protocol.
A2A Protocol Access Methods
After the Agent API is created, callers can access it by following the standard A2A process:
1. The caller sends a request to the AgentCard discovery endpoint on the gateway to obtain the Agent's AgentCard, which includes the name, description, skill list, supported transport protocols, and security requirements.
2. The caller establishes a connection based on the transport protocol declared in the AgentCard and the transport binding you configured on the Agent Service.
3. The caller sends an A2A message, and the gateway forwards it to the backend Agent based on the URL, timeout, and number of retries configured on the Agent Service.
The task lifecycle of the A2A protocol is maintained by the backend Agent, and the gateway does not change the semantics of task states.
Quotas and Limits
Agent Service names must be unique within the same gateway instance.
A single A2A-type Agent Service can be associated with up to 50 Skills.
The maximum timeout for an Agent Service is 600000 milliseconds (10 minutes), and the maximum number of retries is 10.
All Agent Service capabilities require the gateway version to be 3.9.5 or later.