Agent configuration
Use agents in Bitbucket Pipelines to offload work like explaining code, reviewing pull requests, or summarizing changes to an AI assistant. This page explains how to configure those agents so they behave consistently across your pipelines.
On this page, you'll learn how to:
Choose an agent provider.
Configure prompts, either inline or from a reusable skill file.
Use the built‑in default agent and override its settings when needed.
Understand how configuration precedence works between default agents, custom agents, and step‑level overrides.
Agent provider
provider specifies which AI provider the agent uses. You can set it:
On the agent definition, or
As an override on the step
Available values: rovodev and claude.
Note: When you select Claude, this integration is a third-party product. Atlassian does not control and has no liability for third-party products, see Third-Party Agents providers and Bitbucket Agentic Pipelines for more information.
If you don't specify a provider anywhere, Bitbucket Pipelines uses rovodev by default.
Example: use Claude provider in the agent definition
definitions:
agents:
my-agent:
prompt: "Explain this repository"
provider: claude
pipelines:
default:
- step:
script:
- agent: my-agentPrompt configuration
Prompts can be provided inline or via a referenced skill (file).
Inline prompts have a 2,000‑character limit. For longer or reusable prompts, use a skill reference.
Inline prompt
Use an inline prompt for short, simple instructions. Set it directly on the agent definition, or override it at the step level.
Note: The exact prompt format (for example, how you refer to files or tools) may be provider‑specific. Check the provider’s documentation if you need advanced prompt patterns.
Example: inline prompt in the agent definitions
definitions:
agents:
my-agent:
prompt: "Explain this repository"You can also override the prompt at the step level:
definitions:
agents:
my-agent:
prompt: "Explain this repository"
pipelines:
default:
- step:
script:
- agent: my-agent
prompt: "Summarise the recent changes"Skill reference
For longer or reusable prompts, define them as skills in your repository and reference them using the /skill syntax.
Skill locations differ depending on the provider:
Claude:
.claude/skills/
see Claude Code skillsRovo Dev:
.rovodev/skillsor.agents/skills
see Rovo Dev CLI with Agent Skills
definitions:
agents:
my-agent:
prompt: "/review-pr $BITBUCKET_PR_ID"Agent configuration
Use agent configuration to load provider‑specific settings from a file and optionally override individual values per agent or step.
This is useful when you want a different configuration in CI compared to local development.
Config path
config.path points to a provider‑specific configuration file committed in your repository. The file is read at runtime for the selected provider and its settings are used as a base (for example, model, safety settings, and permissions).
File examples:
.claude/settings.json
.rovodev/config.yaml
definitions:
agents:
fix-build-agent:
prompt: "/fix-build"
config:
# Default CI agent settings
path: "./rovodev/config-ci.yml"
pipelines:
default:
- step:
name: Build
script:
- agent: fix-build-agent
config:
# More specific config for build step
path: "./rovodev/config-ci-build.yml"Config overrides
config.overrides provides inline values that take precedence over the loaded config file and defaults. Use it to tweak a subset of settings without duplicating the full config file.
Merge behaviour:
Values are deep‑merged with existing settings.
Arrays are replaced, not concatenated.
Example: Use a shared config file and override a single field
definitions:
agents:
summariser:
prompt: "Summarise recent changes"
provider: claude
config:
path: .claude/settings-ci.json
overrides:
model: sonnet
pipelines:
default:
- step:
name: Summarise changes
script:
- agent: summariser
# optionally, can also be specified on a step level
config:
overrides:
# This will override deny permissions for the agent
permissions:
deny: ["Read(./.env)"]Default agent
Bitbucket Pipelines provides a built‑in default agent you can use out of the box. This is useful when you're starting out or when you only need simple agent behavior.
Use the default agent by specifying it in your step and providing a prompt:
pipelines:
default:
- variables:
- name: PROMPT
description: prompt for the default agent
- step:
script:
- agent: default
prompt: $PROMPTSimilar to custom agents, the default agent can be configured in the definitions section:
definitions:
agents:
default:
provider: claude
pipelines:
default:
- step:
script:
- agent: default
prompt: $PROMPTSettings under definitions.agents.default are also applied to custom agents unless those settings are overridden on the custom agent or at the step level:
definitions:
agents:
default:
provider: claude
my-claude-agent:
prompt: Hello Claude!
pipelines:
default:
- step:
script:
- agent: my-claude-agentThe default agent supports the same configuration fields as a custom agent, and any of them can be overridden on the custom agent:
definitions:
agents:
# by default use claude agent with specific permissions
default:
provider: claude
config:
path: ".claude/settings.json"
overrides:
permissions:
deny:
- "Bash(curl *)"
- "Read(./.env)"
my-claude-agent:
prompt: Hello Claude!
my-claude-agent-with-opus-model:
prompt: Hello Claude!
config:
overrides:
model: opus
pipelines:
default:
- step:
script:
- agent: my-claude-agentConfiguration precedence (highest wins):
Step overrides
Custom agent
Default agent
Related topics
Was this helpful?