Agents API
Agents API - agent management
import { CodeBoltClient } from '@codebolt/clientsdk';
const client = new CodeBoltClient();
Quick Reference
| Method | Description |
|---|---|
changeAgent | Changes the currently active agent. |
createCustomLocalAgent | Creates a custom local agent. |
createFlowAgent | Creates a flow-based agent. |
createRemoteAgent | Creates a remote agent. |
deleteRemixAgent | Deletes a remix agent. |
getAgentConfig | Retrieves the configuration for a specific agent by name. |
getAgentConfigs | Retrieves all agent configurations. |
getAgentFromLocal | Retrieves the agent stored in local storage. |
getAgentProperties | Retrieves the global agent properties. |
getAllRemixAgents | Retrieves all remix agents. |
getFeaturedAgents | Retrieves featured agents from the agent registry. |
getInstalled | Retrieves all installed agents. |
getInstalledAgentsAction | Retrieves action configurations for all installed agents. |
getLocalAgents | Retrieves agents installed from local sources. |
getRecommendedAgents | Retrieves recommended agents based on the current context. |
getRemixAgent | Retrieves a specific remix agent by name. |
getRunningAgents | Retrieves all currently running agents. |
install | Installs an agent from the remote registry. |
installLocal | Installs an agent from a local file path. |
saveRemixAgent | Saves a remix agent. |
startAgent | Starts a new agent instance with the specified configuration. |
stopAgent | Stops a running agent. |
updateAgent | Updates an installed agent to a newer version. |
updateAgentIndex | Updates the agent router index. |
updateAgentProperties | Updates the global agent properties. |
updateRemixAgent | Updates a remix agent. |
Methods
changeAgent
client.agents.changeAgent(data: ChangeAgentRequest): Promise<Agent>
Changes the currently active agent.
Switches the runtime to use a different agent, stopping the current one if necessary. Use this when transitioning between different agent types during a workflow.
| Parameter | Type | Required | Description |
|---|---|---|---|
data | ChangeAgentRequest | Yes | The agent change configuration |
Returns: Promise<Agent> — A promise that resolves to the newly active Agent instance
createCustomLocalAgent
client.agents.createCustomLocalAgent(data: CreateCustomLocalAgentRequest): Promise<Agent>
Creates a custom local agent.
Defines a new agent from scratch on the local filesystem with custom configuration, making it available for use in the runtime.
| Parameter | Type | Required | Description |
|---|---|---|---|
data | CreateCustomLocalAgentRequest | Yes | The custom agent creation configuration |
Returns: Promise<Agent> — A promise that resolves to the created Agent
createFlowAgent
client.agents.createFlowAgent(data: CreateFlowAgentRequest): Promise<Agent>
Creates a flow-based agent.
Defines a new agent that operates based on a visual flow definition, where behavior is determined by connected nodes in a flow graph.
| Parameter | Type | Required | Description |
|---|---|---|---|
data | CreateFlowAgentRequest | Yes | The flow agent creation configuration |
Returns: Promise<Agent> — A promise that resolves to the created Agent
createRemoteAgent
client.agents.createRemoteAgent(data: CreateRemoteAgentRequest): Promise<Agent>
Creates a remote agent.
Registers a new agent that runs on a remote server, allowing CodeBolt to delegate tasks to external agent services.
| Parameter | Type | Required | Description |
|---|---|---|---|
data | CreateRemoteAgentRequest | Yes | The remote agent creation configuration |
Returns: Promise<Agent> — A promise that resolves to the created Agent
deleteRemixAgent
client.agents.deleteRemixAgent(name: string): Promise<void>
Deletes a remix agent.
Permanently removes the specified remix agent from the system.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | The name of the remix agent to delete |
Returns: Promise<void> — A promise that resolves when the remix agent has been deleted
getAgentConfig
client.agents.getAgentConfig(agentName: string): Promise<AgentConfig>
Retrieves the configuration for a specific agent by name.
Returns the full configuration object for the named agent, including its capabilities, settings, and metadata.
| Parameter | Type | Required | Description |
|---|---|---|---|
agentName | string | Yes | The name of the agent to look up |
Returns: Promise<AgentConfig> — A promise that resolves to the AgentConfig for the specified agent
getAgentConfigs
client.agents.getAgentConfigs(): Promise<AgentConfig[]>
Retrieves all agent configurations.
Returns configuration objects for every registered agent in the system.
No parameters.
Returns: Promise<AgentConfig[]> — A promise that resolves to an array of AgentConfig objects
getAgentFromLocal
client.agents.getAgentFromLocal(): Promise<Agent>
Retrieves the agent stored in local storage.
Returns the agent configuration that has been persisted locally, typically the last-used or default agent for the current workspace.
No parameters.
Returns: Promise<Agent> — A promise that resolves to the locally stored Agent
getAgentProperties
client.agents.getAgentProperties(): Promise<AgentProperties>
Retrieves the global agent properties.
Returns system-wide properties that apply to all agents, such as default timeouts, resource limits, and shared configuration.
No parameters.
Returns: Promise<AgentProperties> — A promise that resolves to the AgentProperties object
getAllRemixAgents
client.agents.getAllRemixAgents(): Promise<RemixAgent[]>
Retrieves all remix agents.
Returns every remix agent that has been created in the system.
No parameters.
Returns: Promise<RemixAgent[]> — A promise that resolves to an array of RemixAgent objects
getFeaturedAgents
client.agents.getFeaturedAgents(): Promise<Agent[]>
Retrieves featured agents from the agent registry.
Returns a curated list of agents that are highlighted or promoted in the CodeBolt marketplace.
No parameters.
Returns: Promise<Agent[]> — A promise that resolves to an array of featured Agent objects
getInstalled
client.agents.getInstalled(): Promise<Agent[]>
Retrieves all installed agents.
Returns every agent that has been installed in the current CodeBolt environment, whether from the registry or locally.
No parameters.
Returns: Promise<Agent[]> — A promise that resolves to an array of installed Agent objects
getInstalledAgentsAction
client.agents.getInstalledAgentsAction(): Promise<AgentConfig[]>
Retrieves action configurations for all installed agents.
Returns the action capability definitions for each installed agent, describing what actions they can perform.
No parameters.
Returns: Promise<AgentConfig[]> — A promise that resolves to an array of AgentConfig objects
getLocalAgents
client.agents.getLocalAgents(): Promise<Agent[]>
Retrieves agents installed from local sources.
Returns only agents that were installed from the local filesystem, excluding those from the remote registry.
No parameters.
Returns: Promise<Agent[]> — A promise that resolves to an array of locally installed Agent objects
getRecommendedAgents
client.agents.getRecommendedAgents(): Promise<Agent[]>
Retrieves recommended agents based on the current context.
Returns agents that are suggested based on the current project type, user preferences, or usage patterns.
No parameters.
Returns: Promise<Agent[]> — A promise that resolves to an array of recommended Agent objects
getRemixAgent
client.agents.getRemixAgent(name: string): Promise<RemixAgent>
Retrieves a specific remix agent by name.
Returns the full definition of a remix agent, including its base agent reference and customizations.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | The name of the remix agent to retrieve |
Returns: Promise<RemixAgent> — A promise that resolves to the RemixAgent object
getRunningAgents
client.agents.getRunningAgents(): Promise<Agent[]>
Retrieves all currently running agents.
Returns a list of agents that are actively executing in the runtime.
No parameters.
Returns: Promise<Agent[]> — A promise that resolves to an array of running Agent objects
install
client.agents.install(data: InstallAgentRequest): Promise<Agent>
Installs an agent from the remote registry.
Downloads and registers an agent from the CodeBolt agent marketplace, making it available for local use.
| Parameter | Type | Required | Description |
|---|---|---|---|
data | InstallAgentRequest | Yes | The installation configuration |
Returns: Promise<Agent> — A promise that resolves to the installed Agent
installLocal
client.agents.installLocal(data: InstallLocalAgentRequest): Promise<Agent>
Installs an agent from a local file path.
Loads and registers an agent from the local filesystem, making it available for use in the runtime.
| Parameter | Type | Required | Description |
|---|---|---|---|
data | InstallLocalAgentRequest | Yes | The local installation configuration |
Returns: Promise<Agent> — A promise that resolves to the installed Agent
saveRemixAgent
client.agents.saveRemixAgent(data: RemixAgent): Promise<RemixAgent>
Saves a remix agent.
Creates or saves a remix agent, which is a customized variant of an existing agent with modified prompts, settings, or capabilities.
| Parameter | Type | Required | Description |
|---|---|---|---|
data | RemixAgent | Yes | The remix agent definition to save |
Returns: Promise<RemixAgent> — A promise that resolves to the saved RemixAgent
startAgent
client.agents.startAgent(data: StartAgentRequest): Promise<Agent>
Starts a new agent instance with the specified configuration.
Initializes and launches an agent process in the CodeBolt runtime. The agent will be configured based on the provided request parameters including its type, capabilities, and execution context.
| Parameter | Type | Required | Description |
|---|---|---|---|
data | StartAgentRequest | Yes | The agent start configuration |
Returns: Promise<Agent> — A promise that resolves to the started Agent instance with its runtime details
stopAgent
client.agents.stopAgent(data: StopAgentRequest): Promise<void>
Stops a running agent.
Sends a stop signal to the specified agent, causing it to terminate gracefully.
| Parameter | Type | Required | Description |
|---|---|---|---|
data | StopAgentRequest | Yes | The stop request configuration |
Returns: Promise<void> — A promise that resolves when the agent has been stopped
updateAgent
client.agents.updateAgent(data: UpdateAgentRequest): Promise<Agent>
Updates an installed agent to a newer version.
Applies updates to an already-installed agent, pulling the latest version from the registry or local source.
| Parameter | Type | Required | Description |
|---|---|---|---|
data | UpdateAgentRequest | Yes | The update configuration |
Returns: Promise<Agent> — A promise that resolves to the updated Agent
updateAgentIndex
client.agents.updateAgentIndex(): Promise<void>
Updates the agent router index.
Forces a rebuild of the internal routing index that maps tasks to appropriate agents. Call this after installing or removing agents.
No parameters.
Returns: Promise<void> — A promise that resolves when the index has been updated
updateAgentProperties
client.agents.updateAgentProperties(data: AgentProperties): Promise<AgentProperties>
Updates the global agent properties.
Modifies system-wide agent settings that apply to all agent instances.
| Parameter | Type | Required | Description |
|---|---|---|---|
data | AgentProperties | Yes | The updated agent properties |
Returns: Promise<AgentProperties> — A promise that resolves to the updated AgentProperties
updateRemixAgent
client.agents.updateRemixAgent(name: string, data: RemixAgent): Promise<RemixAgent>
Updates a remix agent.
Modifies the configuration of an existing remix agent.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | The name of the remix agent to update |
data | RemixAgent | Yes | The updated remix agent definition |
Returns: Promise<RemixAgent> — A promise that resolves to the updated RemixAgent