Agents

​

Custom agents in Poolside

Custom agents are reusable agent configurations with their own instructions, tools, and capabilities. They are distinct from the default Poolside Assistant, and you can use them in your IDE or command-line tool (CLI). For general information about AI agents, see How agents work. Use the Agents page in the Poolside Console to create, configure, and manage agents across your organization. Each agent lets you control the model, instructions, tool access, and connected resources that shape how it responds and what it can use at runtime. Each agent can include the following components:

​

Access and security

Role-based permissions and runtime access configuration determine who can access an agent and how it can run.

​

Role-based permissions

Your role permissions determine whether you can create, use, manage, set default agents, or view agent sessions. You must have the Use Agents permission to run an agent. For a complete list of permissions, see Permissions reference.

​

Runtime access enforcement

When you run an agent, you can use only the capabilities that are both:

• Configured on the agent, and
• Permitted for the user

For example:

• If an agent includes MCP servers, knowledge bases, or sandboxes, you can access only the ones your permissions allow.
• If you can run an agent but do not have permission for a specific MCP server, knowledge base, or sandbox attached to that agent, you cannot use that capability during the run.

Adding a capability to an agent does not give you permission to use it.

​

Create an agent

When you create an agent, you choose its model, instructions, tools, and any connected resources such as MCP servers, knowledge bases, and sandboxes. Prerequisites

• You have the Create Agent permission.

The options available during agent creation depend on your organization’s configuration and your permissions. Steps

1. In the Poolside Console, navigate to Agents > Agents.
2. Click New Agent.
   The Create New Agent page opens.
3. For the Agent Name and Model step, do one of the following:
   • To start from an existing agent configuration, click Want to import an agent instead?, then select a JSON file to import. Importing an agent is useful for migrating agents between environments or sharing agent configurations with team members.
   • Otherwise, enter an Agent name and select a Model. The model you select determines the agent’s underlying AI capabilities. For more information, see Models.
4. Optional: For the Agent Instructions step, add instructions to define how the agent behaves and responds. Click Help me generate instructions to get started, or see Prompting best practices. These instructions apply to the agent configuration. When you run the agent in the IDE or CLI, it also uses any local custom instructions from AGENTS.md and .poolside. For details about how these instruction sources work together, see Agent instructions.
   • Be specific about the agent’s role and responsibilities.
   • Define tone and response style.
   • Specify constraints or limitations.
   • Include examples of desired behavior when helpful.
5. Optional: For the Agent Tools step, select the tools the agent can use. For each tool category, click Show tools to view and enable individual tools, or click Enable all to enable all tools in the category. The available tool categories include:
   • Read: View files, inspect code, and browse directories. Read-only and low risk.
   • Write: Create, edit, and delete files. Can modify your codebase and carries medium risk.
   • Shell: Run shell commands and scripts. Can run arbitrary commands, install packages, or modify system state and carries high risk.
6. Optional: For the MCP Servers step, select MCP servers to extend the agent with external tools and integrations.
   MCP is an open standard that lets AI models securely connect to external data sources and tools. For more information and a list of available servers, see the Model Context Protocol documentation.
   • For each MCP server, click Show tools to view and enable individual tools, or click Enable all to enable all tools from that server.
   • To allow users to connect their own MCP servers locally when running this agent, select Allow users to connect to additional MCP servers. This setting applies only to each user’s own runs.
7. Optional: For the Knowledge Bases step, select knowledge bases to give the agent access to relevant documentation, code, and other resources.
   • For each knowledge base, click Enable to make it available to the agent.
8. For the Execution Environment step, choose whether the agent can run in your local environment, in one or more local sandboxes, or both.
   • User-managed environment: Run the agent directly on your machine through the IDE or CLI, optionally using a locally defined sandbox (for example, settings.yaml).
   • Local sandboxes: Run the agent locally in a sandbox environment with server-provided configuration. Click Show sandboxes, then select one or more sandboxes, or click Enable all. For more information, see Sandboxes.
9. Click Create. The agent details page opens.

Agents can perform up to 200 steps per run by default. After you create an agent, you can change this limit.

​

Change the step limit for an agent

Change the maximum number of steps an agent can take during a run. You can set any value from 1 to 1000. Prerequisites

• You have the Manage Agents permission.

Steps

1. In the Poolside Console, navigate to Agents > Agents.
2. Select an agent.
3. Click Edit.
4. On the edit page, enter a value between 1 and 1000 for Max steps.
5. Click Save Changes.

​

Try an agent

After you create an agent, use Try agent to see how to run it across different surfaces. The dialog provides instructions, commands, and configuration snippets to help you start using the agent right away. Prerequisites

• You have the Use Agents permission.

Steps

1. In the Poolside Console, navigate to Agents > Agents.
2. Select an agent.
3. Click Try agent.
4. Select the tab for the surface you want to use:
   • CLI: Run the agent using the Poolside Agent CLI.
   • VS Code / VS: Use the agent from Visual Studio Code or Visual Studio Poolside Assistant extension.
   • ACP: Connect to the agent from JetBrains IDEs and other Agent Client Protocol-compatible clients.
   • Remote Sessions: Access the agent programmatically using the API.

​

Grant access to an agent

Use Grant access to create or update a role with the agent’s required permissions already configured, instead of adding them manually in Organization > Roles. The dialog adds the required permissions based on the agent’s configuration, including any associated resources such as MCP servers, knowledge bases, and sandboxes. Prerequisites

• You belong to a team assigned the tenant-admin role.

Steps

1. In the Poolside Console, navigate to Agents > Agents.
2. Select an agent.
3. Click the ellipsis (…) and select Grant access.
4. In the Grant access to agent dialog, choose how to assign the required permissions:
   • Create a new role: Use this option if you want to create a dedicated role for this agent or if no existing role should have these permissions.
   • Update an existing role: Use this option if a role already exists for the users or teams who should run this agent. Select the role from the dropdown.
5. Click Continue. The Create Role or Edit Role dialog opens in Organization > Roles with the required permissions already added.
6. Complete the role setup:
   • For a new role, click Create Role.
   • For an existing role, review the permissions and click Save.

For more information about creating and managing roles, see Roles.

​

Set a default agent

Designate a default agent for your organization. When you start a session in Poolside Assistant without selecting a specific agent, Poolside Assistant uses the default agent automatically. Prerequisites

• You have the Set Default Agent permission.

Steps

1. In the Poolside Console, navigate to Agents > Agents.
2. Select an agent.
3. Click the ellipsis (…) and select Set as default.

​

Export an agent configuration

Export an agent’s configuration as a JSON file to back it up or reuse it elsewhere. Prerequisites

• You have the Manage Agents permission.

Steps

1. In the Poolside Console, navigate to Agents > Agents.
2. Select an agent.
3. Click the ellipsis (…) and select Export.

The agent configuration downloads as a JSON file.

​

View configuration history

View a timeline of configuration changes for an agent. The history shows what changed, who made the change, and when the change occurred. To audit agent runs and inspect session details, see Agent auditing and trajectories. Prerequisites

• You have the Manage Agents permission.

Steps

1. In the Poolside Console, navigate to Agents > Agents.
2. Select an agent.
3. Click View Recent Changes.
4. In the Recent Changes area, select an entry to open the Config Snapshot dialog, which shows the agent configuration at that point in time and highlights the changes.
5. Optional: To review the complete history, click View Full History. In the Config Full History dialog, select an entry to open the Config Snapshot dialog.
6. Optional: To close the Recent Changes area, click Hide Recent Changes.

​

Revert an agent configuration

Restore an agent to a previous configuration snapshot, including its instructions, tools, MCP servers, knowledge bases, execution environments, and other agent properties. Reverting a snapshot restores the agent configuration but does not revert external resources such as models or MCP servers if those resources changed after Poolside created the snapshot. Prerequisites

• You have the Manage Agents permission.

Steps

1. In the Poolside Console, navigate to Agents > Agents.
2. Select an agent.
3. Click View Recent Changes.
4. In the Recent Changes area, select the entry you want to restore.
   • To find an older entry, click View Full History, then select the entry in the Config Full History dialog.
5. In the Config Snapshot dialog, review the configuration, then click Revert to this version.

​

Delete an agent

Delete an agent when it is no longer needed. This action is permanent and cannot be undone. Prerequisites

• You have the Manage Agents permission.

Steps

1. In the Poolside Console, navigate to Agents > Agents.
2. Select an agent.
3. Click the ellipsis (…) and select Delete.

​

Related resources

• Agent auditing and trajectories