Manage agents by using API operations
As the number of agents grows, creating and verifying configurations one by one in the console becomes inefficient. Agent management API operations allow you to query, create, and modify agents in batches and incorporate agent configurations into your own deployment workflows.
How it works
An agent is uniquely identified by its name in ADA. The Name value is specified at creation time and cannot be changed afterward. All read and write operations locate the agent by this name.
Write operations use optimistic concurrency control. UpdateAgent can carry an ExpectedVersion value. The server compares this value against the current version and rejects the modification if they do not match. When multiple processes modify the same agent concurrently, the later submission receives a conflict error instead of silently overwriting the earlier change.
Each successful write operation generates a new version. ListAgentVersions returns the version list, and GetAgent can retrieve a historical configuration by specifying a version.
Write operations return a receipt that contains AgentId, Name, and the modification time, but not the full agent configuration. To verify the persisted result, call GetAgent after the write operation to read back the configuration.
Usage notes
API operations apply to the tenant and region to which the caller identity belongs. Agents in other regions are not included in the response.
Ownership restrictions also apply. Agents visible only to their creator do not appear in the ListAgents results of other identities, and GetAgent returns an access denied error for those agents.
Session execution is not handled by these API operations. Starting conversations and reading execution progress are currently done through product entry points, including the conversation workbench, IM channels, and scheduled tasks. For more information, see Starting a conversation.
Query the agent list
The list operation can be used both for synchronizing the full inventory and for filtering by conditions. Determine the filtering dimensions before you decide on the parameter combination.
-
Call
ListAgentsand usePageNumberandPageSizefor pagination. For full synchronization, iterate through pages until the number of returned items is less than the page size. -
Use
Scopeto distinguish the source. Set it toSYSTEMto return platform-preset agents, orCUSTOMto return custom agents created within the tenant. When managing custom configurations in batches, always passCUSTOMto prevent preset agents from being included in the synchronization scope. -
Use
Visibilityto filter by ownership. Set it toUSERfor agents visible only to yourself, orTENANTfor agents visible to all members within the tenant. -
Use
Qto perform keyword matching against agent names and descriptions, and useCreatorIdto filter by creator. -
To filter by runtime environment, pass
RequiredRuntimewith a value that matches the runtime declared by the agent.
The response items contain the agent name, display name, description, model configuration, and capability references. Capability associations are returned as references. To obtain the detailed definitions of skills and connectors, call the corresponding API operations separately. For skill-related operations, see Skill management API.
Create an agent
A creation request submits the role definition and capability associations in a single call. Missing fields do not trigger errors but result in an agent with incomplete capabilities. Verify each field before you submit the request.
-
Specify
Name. This field is used to locate the agent in all subsequent calls and cannot be changed after creation. Use a stable, environment-independent identifier. -
Set
DisplayNameandDescription. The description determines whether users can identify the purpose of the agent in the list. -
Set
SystemPromptto declare the responsibility boundaries and output requirements. -
Specify the
Modelconfiguration. If this parameter is not specified, the default model of the tenant is used. -
Associate capabilities:
Skillsdeclares skill references,Connectorsdeclares big data engine connector references,Toolsdeclares tools, andKnowledgeBaseIdsdeclares knowledge bases. You can associate at most one knowledge base. -
Set
Visibility. The default value is visible only to yourself. To share the agent with your team, passTENANT. For more information, see Team collaboration and resource sharing. -
Call
CreateAgentto submit the request, and then callGetAgentwith the returnedNameto read back the result and verify that the capability associations match your expectations.
The read-back step must not be skipped. If a referenced skill or connector does not exist, the creation may still succeed, and the missing reference is only exposed during actual conversations.
Modify and roll back configurations
A modification uses replace semantics, not merge semantics. Even if you want to change only one field, you must verify how the remaining fields are passed to avoid clearing unspecified fields.
-
Call
GetAgentto retrieve the current configuration and record the returned version number. -
Modify the target fields based on the retrieved result and construct an
UpdateAgentrequest. -
Include
ExpectedVersionwith the version number obtained in the first step. If the versions do not match, the operation is rejected. In this case, read the configuration again and retry. Do not force a submission. -
Passing an empty array for
KnowledgeBaseIdsdisassociates the knowledge base, while omitting the field keeps the existing association. The two have different semantics. -
Read back the configuration after the submission to verify the result.
-
To roll back, first call
ListAgentVersionsto find the target version, then callGetAgentwith the specified version to retrieve that version's configuration, and finally submit it as a new version by usingUpdateAgent. A historical version itself is not directly activated.
Delete an agent
Deleting an agent affects more than just the agent itself. Verify dependencies before you proceed.
Before you call DeleteAgent, verify the following three conditions: no running scheduled tasks reference the agent, no IM channels are associated with it, and no other members are actively using a tenant-wide visible version. A task discovers the agent no longer exists only at trigger time, which results in a task failure rather than a configuration alert. For more information, see Scheduled tasks.
Apply to production environments
Agent configurations are managed by version control. Maintain configurations as files in a code repository and use APIs to deploy them to each environment. Differences between environments can be directly compared without relying on manual recall.
The deployment process consists of four fixed steps: read, compare, submit, and read back. A deployment that skips the read-back step cannot confirm the persisted result. A success response from a write API only indicates that the request was accepted.
Always include ExpectedVersion in automated deployments. When the deployment process runs in parallel with manual modifications, the absence of version validation may cause manual changes to be silently overwritten.
Authorize delete operations separately from other write operations. Do not grant DeleteAgent permissions to credentials used by batch scripts. Instead, perform deletions separately after manual confirmation. For more information, see API overview and authentication.
Quotas and limits
|
Item |
Description |
|
|
Cannot be modified after creation. This value is used as the identifier for all API calls. |
|
Knowledge base attachment |
Each agent can have at most one knowledge base attached. |
|
Ownership |
Valid values: |
|
Write operation response |
Only an operation receipt is returned. To obtain the full configuration, you must perform a read-back. |
|
Version |
Each successful write operation generates a new version. Historical versions can be read but cannot be directly activated. |
FAQ
-
Q: The agent was created successfully but returns a capability unavailable error during conversation.
A: The create API does not validate whether the referenced attachments exist. Verify that all references in
Skills,Connectors, andKnowledgeBaseIdshave been created in the current tenant and that the calling identity has access to them. -
Q: Why was the uncommitted configuration cleared after a modification?
A: A modification uses overwrite semantics. Construct the request based on the response of
GetAgentand modify only the target fields. Do not assemble the request from an empty object. -
Q: How do I handle a version conflict?
A: Call
GetAgentagain to retrieve the latest configuration and version number, apply your changes based on the new version, and then submit. A conflict indicates that another change was made in the meantime. If you removeExpectedVersionand retry directly, that change will be overwritten. -
Q: Can I initiate a conversation by using an API?
A: Conversations are currently initiated through product entry points, including the conversation console, IM channels, and scheduled tasks. The APIs provide management capabilities for agents. The scope of available APIs is subject to the version published on the OpenAPI portal.