Managed agents

​

Overview

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.

​

Access and security

​

Role-based permissions

​

Runtime access enforcement

• Configured on the agent, and
• Permitted for you

• If an agent includes MCP servers, repositories, 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, repository, or sandbox attached to that agent, you cannot use that capability during the run.

​

Create an agent

• You have the Create Agent permission.

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 what the agent does, including its role, tasks, and purpose. Click Help me generate instructions to get started.
   These instructions apply to this agent configuration. When you run the agent in the IDE or CLI, Poolside also uses any local instruction files (AGENTS.md and .poolside). Agent instructions take priority over AGENTS.md and .poolside. For details, 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. For the Execution Environment step, choose where the agent runs and, when applicable, which sandboxes it can use.
   • To make the agent available in the IDE or CLI, enable at least one IDE/CLI option:
     • Local environment: Runs on the user’s machine, optionally using a local sandbox defined in their user settings, such as settings.yaml. Enabled by default.
     • Managed local sandbox: Runs on the user’s machine with organization-managed sandboxes. Click Show sandboxes, then select one or more sandboxes, or click Enable all.
   • To make the agent available in Poolside Chat, enable the Web option:
     • Local browser: Runs in Poolside Chat in the user’s browser.
   For more information, see Sandboxes.
6. 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.
   • Context: Enable additional context and specialized capabilities. Click Show tools to configure individual context tools:
     • List secrets: Let the agent see which secrets are available. For more information, see Secrets and Credentials.
     • Question: Let the agent ask one or more questions and wait for your answers.
     • Skill: Let the agent invoke skills for complex, specialized tasks. For more information, see Skills.
     • Switch mode: Let the agent switch between execution modes, such as build and plan modes. For more information, see Plan mode.
7. 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.

8. Optional: For the Knowledge Sources step, select indexed repositories to give the agent access to relevant documentation, code, and other resources.
   • For each repository, click Enable to make it available to the agent.
   For more information, see Repositories.
9. Optional: For the Skills step, select remote skills you want to make available to the agent. Skills are organized by repository.
   The same repository can appear in both steps: in Knowledge Sources when it is indexed, and in Skills when Poolside discovers skills in it.
   • For each repository, click Show skills to view and enable individual skills, or click Enable all to enable every discovered skill.
   For more information, see Skills.
10. Click Create. The agent details page opens.

• Add credentials to make secrets available to the agent at runtime.
• Change the step limit to control how many steps the agent can take per run. The default is 200.
• Try the agent to verify it behaves as expected.
• Grant access to the agent so that users in your organization can run it.

​

Add credentials to an agent

• You have the Manage Agents permission.
• The credentials you want to add are configured for agent use in Security > Credentials.

1. In the Poolside Console, navigate to Agents > Agents.
2. Select an agent.
3. Click Edit.
4. On the Credentials tab, select the credentials you want to make available to the agent.
5. Go to the Tools tab and enable List secrets in the Context category. Without this tool, the agent cannot access the selected credentials.
6. Click Save Changes.

​

Change the step limit for an agent

• You have the Manage Agents permission.

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

​

Try an agent

• You have the Use Agents permission.

1. In the Poolside Console, navigate to Agents > Agents.
2. Select an agent.
3. Click Try agent.
4. Select where you want to try this agent and follow the instructions for that option:
   • CLI: Run the agent using the Poolside Agent CLI.
   • VS Code / VS: Use the agent from the Poolside Assistant extension for Visual Studio Code or Visual Studio.
   • 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, repositories, and sandboxes.

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

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.

​

Set a default agent

• You have the Set Default Agent permission.

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

• You have the Manage Agents permission.

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

​

View configuration history

• You have the Manage Agents permission.

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

• You have the Manage Agents permission.

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

• You have the Manage Agents permission.

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

​

Related resources

• Sandboxes
• MCP servers
• Repositories
• Skills