Skip to Content
Skip to Content
Manage agents

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 --json

Select 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 list

Check 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_ID

Use 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:

FieldPurpose
displayNameDisplay name
shortDescription, descriptionShort and detailed descriptions
modelNameModel ID to use
instructionAgent instructions
expectedInstructionUpdates only if the current instructions match the expected value. If concurrent edits cause a conflict, retrieve the latest content.
knowledgeBundleIdListArray 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 templates
  • disable and enable change the enabled state, subject to organization policy and permissions.
  • share queries the current sharing settings. It does not change who the agent is shared with.
  • templates lists 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 --force

Check 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." --json

You 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." --json

To 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.yaml

Use -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.

Last updated on