Skip to main content

Agentic Tools and Toolboxes

Bosun agents can interact with your codebase and external services using a set of specialized tools organized into toolboxes. These tools provide agents with specific capabilities, allowing them to perform actions like reading files, executing shell commands, or creating pull requests.

Toolboxes​

Toolboxes are collections of related tools that an agent can be granted access to. By specifying which toolboxes an agent can use, you control its operational scope and capabilities.

Here are the currently available toolboxes:

  • repository_read: Grants the agent permission to read files and directories within the connected repository.
  • repository_write: Grants the agent permission to modify, create, or delete files and directories within the connected repository.
  • dangerous: Provides access to powerful, potentially system-altering capabilities, including:
    • Shell access: Execute arbitrary shell commands.
    • Git access: Perform Git operations (e.g., git add, git commit). Although the toolbox is named "dangerous", it is perfectly safe in the code environment. However, it does enable the agent to do virtually anything, and for the sake of focus you might want to avoid giving it this toolbox unless necessary.
  • research: Equips the agent with research capabilities, including:
    • URL fetching: Access and read content from specified web URLs.
    • Web search: Perform searches on the internet to gather information.
    • GitHub search: Search for repositories, code, and issues on GitHub.

Tools​

Beyond the general capabilities provided by toolboxes, specific tools offer fine-grained functionality. These tools can have their own configurations and are often used for common, complex operations.

create_or_update_pull_request​

This is a versatile tool designed for managing pull requests. It can create a new pull request or update an existing one if a branch with pending changes already exists. This "upsert" behavior means you can call it multiple times in a workflow without creating duplicate PRs.

Optional Settings:

  • draft (boolean): If set to true, the pull request will be created or updated as a draft. If false (or omitted), it will be a standard pull request, ready for review.

Example Usage:

  - name: Create a draft pull request
    agent:
      extends: Default
      role: "You create pull requests to prepare for automated work."
      instructions: "Create a draft pull request for the changes made by the previous step."
      toolboxes: [repository_read, dangerous]
      tools:
        - name: create_pull_request
          extends: create_or_update_pull_request
          with:
            draft: true
            title: "feat: Implement new feature"
            body: "This PR introduces the new feature as per the task instructions."

  - name: Update the pull request to ready for review
    agent:
      extends: Default
      role: "You update pull requests with completed automated work."
      instructions: "Update the existing pull request with the latest changes and mark it as ready for review."
      toolboxes: [repository_read, dangerous]
      tools:
        - name: create_pull_request
          extends: create_or_update_pull_request
          with:
            draft: false # Marks the PR as ready for review
            title: "feat: New feature implemented and ready for review"
            body: "All automated work for the new feature is complete. Please review."

Bosun's tool and toolbox system is designed to be extensible, with new capabilities being added regularly to enhance agent functionality.

Repository Context Files​

When you connect a repository, Bosun looks for a top-level AGENTS.md file. If it exists, the file is automatically injected into the context that agents receive. Use it to document coding conventions, review checklists, or any recurring instructions you want agents to follow—no extra configuration needed.