Skip to main content

Agentic Tools and Toolboxes

Bosun agents interact with your codebase and external services through specialized tools organized into toolboxes. Each toolbox gates a set of capabilities, giving you fine-grained control over what an agent may do.

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 capabilities, including:

    • Shell access: Execute arbitrary shell commands.
    • Git access: Perform Git operations (e.g., git add, git commit).
    warning

    The dangerous toolbox lets the agent run any shell command inside the repository workspace. Only enable it for steps that truly need full system access. Coding agents have it enabled by default.

  • 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_repos: Native GitHub repository inspection toolbox for reading repository content and history with shared repository defaults.

  • github_issues: Native GitHub issue toolbox for reading, searching, creating, updating, and commenting on issues.

  • github_pull_requests: Native GitHub pull request toolbox for reading, searching, updating, reviewing, and commenting on pull requests.

  • code_docs: Lets the agent index and query dependency documentation (public registries or your private workspace) via the code_docs tool. Enable it when you need API usage answers that are not already present in the run context.

  • jira: Native Jira Cloud toolbox that lets agents discover projects, search issues, fetch details, create and edit issues, add comments, and trigger workflow transitions. It uses a Jira user email and personal API token, shared across all Jira tools in the step.

  • sentry: Sentry toolbox that lets agents discover organizations and projects, list releases and issues, inspect issue timelines and tag values, and update issues using managed Sentry credentials or explicit token settings.

GitHub toolboxes (repositories, issues, pull requests)​

Bosun provides native GitHub tooling through three focused toolboxes. All three share the same optional toolbox settings:

  • owner: Default GitHub repository owner.
  • repo: Default GitHub repository name.

If these settings are omitted, Bosun uses the connected primary repository owner and name automatically.

github_repos​

Use this toolbox when an agent needs repository-level GitHub reads:

  • Get file contents from GitHub
  • Search code in a repository
  • List branches
  • List commits

github_issues​

Use this toolbox when an agent needs issue workflows:

  • Get issue details
  • List issues
  • Search issues
  • Create issues
  • Update issues
  • Add issue comments

github_pull_requests​

Use this toolbox when an agent needs pull request workflows:

  • Get pull request details
  • List pull requests
  • Search pull requests
  • Update pull requests
  • Write pull request reviews
  • Add pull request review comments
  • Get pull request files, comments, reviews, and check runs

Enabling GitHub toolboxes in manifests​

steps:
  - id: triage-and-review
    agent:
      extends: Coding
      toolboxes:
        - name: github_issues
          with:
            owner: "acme"
            repo: "platform-api"
        - name: github_pull_requests
          with:
            owner: "acme"
            repo: "platform-api"
      instructions: |
        Review open issues, then inspect related pull requests and leave
        actionable review feedback.

starts_with: triage-and-review
edges: []

Ad-hoc documentation retrieval (code_docs)​

The code_docs toolbox exposes Bosun’s ad-hoc documentation engine so agents can answer API-level questions about any package referenced in the run. When the tool is invoked, Bosun:

  1. Resolves the package through the appropriate registry or the active workspace, then (for private packages) checks out the canonical repository path before indexing.
  2. Harvests documentation sources: README.* files, docs/, doc/, or site/ directories, curated registry links, and any generated outputs (Cargo doc, Typedoc, PyDoc, Storybook, or other scripted commands defined by the package).
  3. Builds an org-scoped vector index and runs the query using the latest documents.

Because this happens on demand, every tool call captures the package’s current documentation—even for internal libraries that only exist within your repository or registry.

Enabling the toolbox in manifests​

Add code_docs wherever an agent may need to answer SDK usage questions:

steps:
  - id: investigate-sdk-regression
    agent:
      extends: Coding
      toolboxes:
        - repository_read
        - code_docs
      instructions: |
        Only call `code_docs` when you need a function signature or usage example
        that does not already exist in the task context. Provide the full package
        name and a specific question ("How do I use FooClient.upload?"), then
        summarize the answer with citations.

starts_with: investigate-sdk-regression
edges: []

The tool enforces the language argument so the agent must specify which registry to consult (rust, javascript, python, etc.). Encourage precise prompts in your agent instruction block so the model knows when and how to call the tool.

Public vs. private documentation​

  • Public packages share an index across organizations. Repeated queries become faster because results are cached globally.
  • Private packages are scoped to your organization.
  • Bosun automatically checks out private packages that live inside node_modules (or similar vendor paths) so it can run generators outside the dependency tree and keep your workspace clean.

Jira toolbox (Jira Cloud via personal token)​

The jira toolbox gives agents a native way to work with Jira Cloud issues from inside a workflow. It exposes a family of tools for:

  • Listing visible projects and project issue types
  • Discovering create-field metadata for a project and issue type
  • Searching for issues, or fetching a specific issue by key or id
  • Creating, editing, and commenting on issues
  • Listing and applying workflow transitions

All Jira tools in a step share a single configuration so you only need to set up authentication and defaults once.

Authentication and configuration​

The Jira toolbox uses a personal Jira Cloud API token and user identity. You can configure it either via repository secrets or per-step with settings on the toolbox.

The toolbox understands these settings:

  • base_url: Jira Cloud base URL, for example your https://your-company.atlassian.net/ site URL.
  • user_email: Jira user email used for API authentication.
  • api_token: Jira API token associated with that user.
  • project_key: Optional default project key used by tools that operate on a project.

For each field, Bosun first looks at the toolbox with settings on the step. If they are not present, it falls back to repository secrets with these names:

  • JIRA_BASE_URL
  • JIRA_USER_EMAIL
  • JIRA_API_TOKEN
  • JIRA_PROJECT_KEY (optional default project key)

When the required values are missing, Jira tools fail fast and include guidance in the error message showing which settings or secrets need to be configured.

Enabling the Jira toolbox in manifests​

Add the jira toolbox to any agent that needs to read or update Jira issues. A typical pattern is to wire repository or task inputs into the toolbox settings and keep the personal API token in a secret.

steps:
  - id: triage-jira-issues
    agent:
      extends: default
      role: Jira issue triage
      toolboxes:
        - name: repository_read
        - name: jira
          with:
            base_url: "{{ inputs.jira_base_url }}"
            user_email: "{{ inputs.jira_user_email }}"
            api_token: "{{ inputs.jira_api_token }}"
            project_key: "{{ inputs.jira_project_key }}"
      instructions: |
        Use the Jira tools to inspect recent issues for the configured project.
        Summarize the newest issues and, when appropriate, update their status
        or add comments with your findings.

inputs:
  jira_base_url:
    type: String
    required: true
  jira_user_email:
    type: String
    required: true
  jira_api_token:
    type: String
    required: true
  jira_project_key:
    type: String
    required: true

starts_with: triage-jira-issues
edges: []

Sentry toolbox (Sentry issues and releases)​

The sentry toolbox lets agents investigate and triage Sentry issues directly from a workflow. It exposes native tools for:

  • Listing accessible organizations and projects
  • Listing releases for an organization or specific project
  • Searching and listing issues in an organization or project
  • Fetching full issue details and recent events
  • Inspecting tag values (for example release, environment, or user) on a specific issue
  • Updating issues (status and assignee)

All Sentry tools in a step share a single configuration so you only need to set up authentication and defaults once.

Authentication and configuration​

The Sentry toolbox supports managed authentication in Bosun, plus explicit credentials when you need overrides.

The toolbox understands these settings:

  • access_token: Sentry API token used for all Sentry API calls.
  • organization_slug: Default Sentry organization slug used by tools that operate at the organization or project level.

Resolution order:

  1. If you install the Sentry app in Organization Settings → Event sources, Bosun automatically uses managed Sentry credentials for runs in that organization.
  2. If you set with.access_token and with.organization_slug, those values are used.
  3. If with values are omitted, Bosun falls back to repository or organization secrets with these names:
  • SENTRY_ACCESS_TOKEN
  • SENTRY_ORGANIZATION_SLUG

When no managed integration or explicit credentials are available, Sentry tools fail fast with guidance on which settings or secrets to add.

Because the toolbox shares configuration across all Sentry tools in the step, you can safely mix organization discovery, issue search, and issue updates without re-declaring credentials.

Enabling the Sentry toolbox in manifests​

Add the sentry toolbox to any agent that needs to inspect or update Sentry issues as part of a task. With a managed Sentry connection, you can keep the toolbox configuration minimal.

steps:
  - id: investigate-sentry-issue
    agent:
      extends: Coding
      role: Sentry issue investigation
      toolboxes:
        - name: repository_read
        - name: sentry
          with:
            organization_slug: "bosun"
      instructions: |
        Use the Sentry tools to look up the issue, inspect recent events and tag values,
        and propose a remediation plan. Include a link back to the Sentry issue in your summary.

inputs:
  sentry_issue_id:
    type: String
    required: true

starts_with: investigate-sentry-issue
edges: []

You can omit organization_slug from the toolbox settings when you prefer to manage it centrally via the SENTRY_ORGANIZATION_SLUG secret. If your organization has a managed Sentry connection, you can also omit access_token and let Bosun provide credentials automatically. Individual tools may still accept project slugs, issue ids, or filters as arguments; the shared toolbox settings just keep authentication and organization defaults in one place.

For workflows that start from Sentry events (for example via webhook-based workflow triggers), combine the Sentry toolbox with trigger mappings so that issue ids, project slugs, and environment tags are passed into the task inputs. This keeps your remediation agents close to the Sentry issues that launched the automation.

Repository Context Files​

When you connect a repository, Bosun automatically injects guidance from AGENTS.md files into every agent. The resolver looks for .bosun/AGENTS.md first and falls back to the repository-root AGENTS.md if the scoped file is missing. No manifest changes are required—any agent step that targets the repository receives these instructions before its own prompt content, keeping organization-wide guardrails consistent across runs.

Render context access​

Bosun now exposes repository metadata directly inside the render context so templates can reference repository information without hard-coding paths. The repositories object is available anywhere templating runs (agent instructions, run commands, for_each inputs, etc.). Each entry inside repositories is keyed by the repository’s project_name and currently includes:

  • name: the project name, matching the key you use inside repositories.
  • path: the executor’s absolute path to that repository checkout.

This makes it easy to generate instructions or commands that depend on the primary checkout or on secondary repositories included in the task.

Conversation context and audit summaries​

Bosun’s default coding agents ship with Context Compression, an experimental CAT-inspired summarizer that rewrites long conversations into durable audit trails. Instead of steering the next tool call, these summaries act as a second-order record of everything the agent tried, why it made key decisions, and which artifacts it produced. That makes multi-hour tasks easier to review later or to resume in a follow-up run without replaying every log message.

What the summarizer captures​

Context Compression v2 runs automatically after a few completions or whenever the session nears the model’s context window. It:

  • Replays the recent user/agent exchange and bundles it into a structured markdown layout (Task semantics, Decision log, Audit trail, Outcome summaries, Relevant files, Open issues).
  • Expands every tool call into an explicit audit entry with the tool name, key arguments, result type (text, fail, stop), and any artifacts or files referenced.
  • Includes the latest git diff snippet so reviewers can connect the prose summary to exact file changes.
  • Threads the previous summary into the prompt as read-only context so the new summary consolidates everything learned so far without drifting.
  • Appends a short reminder to tie off unfinished work (“If there are open issues… do your best to complete your task”) so people picking up the run know whether anything remains.

Because audit summaries live directly in the session history, Bosun can collapse dozens of chat turns while still preserving a searchable log of decisions, tool executions, and file edits. The summaries also emit as dedicated summary entries in the session log, so teammates scanning a run can expand just the durable checkpoints instead of scrolling linearly.

Why it improves audit trails​

  • Traceability: Every live diff, shell run, plan update, or custom tool call shows up in the audit log with parameters and outcomes, making it easy to answer “what changed and why?” without parsing raw tool output.
  • Durable context: When a run spans multiple days (or when a second agent takes over), the summarizer supplies the minimal facts needed to continue safely—goal, constraints, outstanding issues, and the files touched so far.
  • Noise reduction: Bosun strips forward-looking suggestions from these summaries to avoid steering the next turn. Only completed actions, decisions, errors, and artifacts make it through, so the audit trail stays factual.

Working with CAT summaries in manifests​

No manifest changes are required to enable the summarizer, but you can lean on its structure in downstream steps:

steps:
  - id: summarize-audit
    agent:
      extends: Coding
      instructions: |
        Read the latest conversation summary and draft a changelog note for humans.
        Focus on the audit trail entries for tooling decisions and any open issues.

starts_with: summarize-audit
edges: []

Because the summaries live in the session history, any agent can call {{ history | json_encode() }} (or fetch the dedicated summary messages from the Sessions API) to build higher-level reports. This is useful for compliance exports, changelog automation, or dashboards that need concise status snapshots without ingesting the entire transcript.

Experimental feature

Context Compression v2 is rolled out as an experimental default. Expect the schema and cadence to evolve—Bosun treats new updates as the latest behavior, so you can rely on the structured layout above even as the implementation iterates.