Manage agents
View installed agents and change their enabled state. AI Operators can also create, edit, and delete agents. Chat and export commands are available when permitted by the CLI version and server.
View lists and details
aipctl agent list
aipctl agent get AGENT_ID
aipctl agent get AGENT_ID --jsonSelect an ID from the list and check the name, description, and required integrations. These commands query settings; they do not send questions to an agent.
Create an agent
Save the following as agent.json. This basic example creates a custom agent with a name and description.
{
"agentType": "CUSTOM",
"custom": {
"displayName": "Weekly report assistant",
"shortDescription": "Organizes weekly work reports."
}
}aipctl admin agent create ./agent.json
aipctl agent listCheck the agent using the returned ID, then complete the required settings, including its model and instructions. Creation alone does not complete every setting or enable the agent.
Change settings
This example changes a custom agent’s name and description. Save it as agent-update.json.
{
"agentType": "CUSTOM",
"custom": {
"displayName": "Team weekly report assistant",
"shortDescription": "Organizes the team's weekly work."
}
}aipctl admin agent update AGENT_ID ./agent-update.json
aipctl agent get AGENT_IDUse settings appropriate to the agent type. Passing the entire details query result as an update request is not supported.
You can also change a custom agent’s model and instructions. Find an available model ID with aipctl model list, then prepare these settings.
{
"agentType": "CUSTOM",
"custom": {
"modelName": "MODEL_ID",
"instruction": "Organize weekly work into completed tasks, work in progress, and next steps."
}
}Replace MODEL_ID with a model ID available in the organization. Save the settings in another JSON file, apply them with the same admin agent update command, and check the details again. Model and instruction changes affect subsequent responses.
Key fields for custom agent updates:
| Field | Purpose |
|---|---|
displayName | Display name |
shortDescription, description | Short and detailed descriptions |
modelName | Model ID to use |
instruction | Agent instructions |
expectedInstruction | Updates only if the current instructions match the expected value. If concurrent edits cause a conflict, retrieve the latest content. |
knowledgeBundleIdList | Array of knowledge bundle IDs to connect. Access to that knowledge is required. |
These fields are for custom agents. Do not assume the same settings apply to built-in agents.
Check enabled state and sharing
aipctl agent disable AGENT_ID
aipctl agent enable AGENT_ID
aipctl admin agent share AGENT_ID
aipctl admin agent templatesdisableandenablechange the enabled state, subject to organization policy and permissions.sharequeries the current sharing settings. It does not change who the agent is shared with.templateslists templates you can refer to when creating an agent.
Delete an agent
aipctl agent get AGENT_ID
aipctl agent disable AGENT_ID
aipctl admin agent delete AGENT_ID --forceCheck whether automations or other tasks use the agent before deleting it. If the server reports that it is in use, resolve those dependencies first.
Chat with an agent
You need the agent ID and permission to run it. Use the web interface if chat execution is restricted in your environment.
For a new conversation, specify an installed agent ID.
aipctl agent chat --agentId AGENT_ID --message "Summarize this week's work." --jsonYou can use -m instead of --message. Save the conversationId from the JSON result to continue the same conversation.
aipctl agent chat --conversation-id CONVERSATION_ID -m "Prioritize the tasks as well." --jsonTo pass text from a file through standard input:
aipctl agent chat --agentId AGENT_ID --json < ./question.txt--message takes precedence over standard input. Sending a request runs the agent and may incur usage. After a timeout or disconnection, check the result in the web interface or conversation queries before resending the same question. If the command is unavailable or rejected, chat through the web interface.
Export as YAML
Check your export permissions before running:
aipctl admin agent export AGENT_ID --output ./exports/agent.yamlUse -o as an alias for --output. If omitted, the file is saved as AGENT_ID.yaml in the current folder. Existing files at the destination are overwritten. Check the file path in the success message. Exported settings may include work instructions, so consider who can access the file. If export is rejected, check your permissions and server support.