---
title: "Aviator: HubSpot's Agent Harness"
summary: 'Aviator is the Java agent harness behind Breeze Assistant and agents across HubSpot. It runs the agent loop, works with any model, scales to thousands of tools, and gives agents skills and a sandboxed computer.'
date: 2026-11-12
authors: [ze-ev-klapow]
topics: [AI, Backend]
cover:
  scene: aviator-hubspots-agent-harness
  alt: "Aviator’s mascot, a grinning little plane in a flying helmet and goggles, flies a loop-the-loop past three crates that light up as it passes."
---

In June 2025, we started looking for an agent framework that teams across HubSpot could build on. Agents were quickly becoming a core part of how we built software, both internally and in our product, but agent implementations at the time varied wildly in terms of features, support, and reliability. Each team building an agent would make different choices, from model selection to architecture.

As many people have discovered, writing the first version of an agentic loop is easy. One can find [a plethora](https://fly.io/blog/everyone-write-an-agent/) [of posts](https://ampcode.com/how-to-build-an-agent) talking about how they wrote an agent in [100 lines of code](https://thebeach.dev/posts/lisp-agent/). Scaling a harness to hundreds of teams is a different problem. As teams began building agents at HubSpot, we found we were repeating the same mistakes over and over, leading to agents that were slower, more expensive, and less reliable than they needed to be. Prompt caching, tool calling, and context management are easy to get subtly wrong, and each team was learning that on its own (even with AI writing most of the code!). We wanted to solve those problems once, so that a fix or an improvement would reach every agent, and every customer using one, at the same time.

While a wealth of tooling already existed in languages like TypeScript and Python, there were few options for building agents in Java, and none we found fit what we needed. Most of HubSpot's backend is Java, and we wanted agents to live inside the services teams already owned, using the same tools, data, and deployment process as the rest of their code. So we decided to build our own. That became Aviator, which is now the core harness that powers agents within HubSpot.

## How we got here

Some teams at HubSpot had begun building agents, while most were still making direct, one-off LLM calls, sometimes with custom tool calling setups. Our DevEx AI team had been experimenting with [smolagents](https://github.com/huggingface/smolagents) for internal tooling. It worked, but integrating Python agents with our Java services was a lot of work. We wanted teams to be able to add an agent to a service they already owned and deploy it with the rest of their code.

<Sidenote n={1}>CHIRP is HubSpot's internal RPC framework.</Sidenote>

At the same time, we had been developing our internal CHIRP<Ref n={1} /> tools framework as part of our MCP servers, which had drastically lowered the barrier to building AI tools. Teams could add annotations to an existing RPC and expose it as a tool, with the schema generated from its request type.

This led us to ask: what if we could make building an agent just as easy? To this end we set a target: make it possible to write an agent in under 20 lines of Java.

## An agent in 20 lines

The framework we ended up with, called Aviator, lets us write an agent anywhere in our infra in just a few lines of Java code:

```java title="PipelineAssistant.java" {4-5}
AviatorAgent agent = agentFactory.newBuilder()
    .withSystemPrompt("You are a sales pipeline assistant...")
    .withModelClientProvider(() -> glmClient)
    .addChirpTool("DealTools#searchDeals")
    .addChirpTool("DealTools#getDealActivity")
    .build();

try (AviatorAgentConversation convo = agent.startConversation()) {
    AviatorMessage answer = convo
        .sendAsync(textPrompt("Which deals closing this quarter need follow-up?"))
        .getTerminalMessage();
}
```

Critically `addChirpTool` allowed us to simply re-use RPCs from our existing RPC framework to quickly and easily add capabilities to our agents, without requiring engineers to take on a lot of net new work.

It became quickly apparent just how powerful this could be. In one example, during our infrastructure hackathon, an infra team that had never built an agent before had a debugging agent working in about fifteen minutes using their existing RPCs as tools.

As more teams adopted Aviator, we wanted the same approach to hold: they should be able to add capabilities and try new models without building another agent stack.

## Switzerland of Models

Teams were already building custom agents with different models, so Aviator needed to be model agnostic from the start. Our goal was to abstract away vendor-specific API details so an agent would never be locked into a particular model or provider.

Aviator defines a provider-agnostic transcript format for messages, tool calls, and results. Model clients translate between that format and each provider's API. Switching providers includes adapting the history: remapping tool-call identifiers and removing incompatible reasoning blocks so the next model can consume it.

We can even switch models mid-conversation, picking up with the existing messages and tool results. That lets us fall back to another provider during an outage or move to a more capable model when a task needs it.

<CodeTabs>

```json title="Aviator transcript" caption="One tool call and its result, made while the conversation ran on OpenAI: as Aviator stores it, and as it is sent to each provider (shortened). When the next turn goes to Anthropic, **the call's ID is rewritten with the prefix Anthropic expects**, and the result's reference to it changes to match."
[
  {
    "role": "ASSISTANT",
    "content": [
      {
        "type": "TOOL_USE",
        "id": "fc_68a1",
        "callId": "call_abc123",
        "name": "searchDeals",
        "input": { "closeDate": "this_quarter" }
      }
    ]
  },
  {
    "role": "USER",
    "content": [
      {
        "type": "TOOL_RESULT",
        "toolUseId": "call_abc123",
        "toolName": "searchDeals",
        "content": "{ \"deals\": [ ... ] }"
      }
    ]
  }
]
```

```json title="Sent to OpenAI"
[
  {
    "type": "function_call",
    "id": "fc_68a1",
    "call_id": "call_abc123",
    "name": "searchDeals",
    "arguments": "{ \"closeDate\": \"this_quarter\" }"
  },
  {
    "type": "function_call_output",
    "call_id": "call_abc123",
    "output": "{ \"deals\": [ ... ] }"
  }
]
```

```json title="Sent to Anthropic"
[
  {
    "role": "assistant",
    "content": [
      {
        "type": "tool_use",
        "id": "toolu_call_abc123",
        "name": "searchDeals",
        "input": { "closeDate": "this_quarter" }
      }
    ]
  },
  {
    "role": "user",
    "content": [
      {
        "type": "tool_result",
        "tool_use_id": "toolu_call_abc123",
        "content": "{ \"deals\": [ ... ] }"
      }
    ]
  }
]
```

</CodeTabs>

This common format has had a number of other benefits: The same format lets all of our agents speak to each other. We can pass a transcript from one agent to another, or resume a conversation with a different agent's prompt, tools, and model. This has allowed us to easily implement some interesting patterns: for example, we can run a fast triaging agent on an error and later "upgrade" that transcript to a more complex coding agent, without losing context.

The transcript is also the complete state of a conversation, which effectively gives our agents a durable log. It serializes to JSON, so an application can checkpoint it to storage and resume from it later, on a different machine, minutes or days afterwards. An agent can pause while it waits for a human to approve a tool call or for a subagent to finish, and when it resumes it picks up exactly where it left off.

We have built rich debugging and tracing tooling based on this format, allowing developers to easily ask questions like “would this conversation have gone better with a system prompt tweak?”

<Chart
  type="trace"
  caption="An Aviator transcript rendered as a trace."
  x="Time since the prompt arrived"
  unit="s"
>{`
span, start, end, depth
The whole turn, 0, 32.6, 0
Model call 1, 0, 3.4, 1
Load 2 skills and read a file, 3.36, 3.39, 2
Model call 2, 3.4, 9.2, 1
2 CRM searches and a file read, 9.2, 10.3, 2
Model call 3, 10.4, 16.7, 1
A record summary and its timeline, 16.7, 17.8, 2
Model call 4, 17.8, 25.4, 1
Draw the answer's cards, 25.42, 25.46, 2
Model call 5: the answer, 25.5, 32.6, 1
`}</Chart>

## Scaling tool calling

Nearly immediately, we ran into the problem of having far too many tools. Reusing existing services made it easy to add tools and accelerated adoption. Very quickly, agents like Sidekick, our primary engineering assistant, needed access to over 3,000 tools. Aviator bundles a number of solutions which agent builders can choose from to help scale tool calling in their agents.

### Tool Search

Aviator allows engineers to mark tools as "deferred." Their definitions stay out of the agent's initial context and become available through tool search.

```java
builder
    .addDeferredChirpTool("DealTools#searchDeals")
    .addDeferredChirpTool("DealTools#getDealActivity");
```

Here again, Aviator helps abstract over various vendor APIs. Anthropic and OpenAI, for example, each have hosted (but subtly different) tool search implementations, which Aviator leverages when available in order to be as in-distribution as possible for that model. For models we self-host, we generally lack these sorts of server-side tools, and instead Aviator provides a dedicated internal search index, generated on the fly based on the specific agent configuration.

### Packaging knowledge into skills

Finding a tool is useful, but often fails to give the agent context on how and when to use a tool. The industry has converged around the [Skill spec](https://agentskills.io/specification) as a way to provide agents with process-level instructions on how to complete a task, and Aviator brings native `SKILL.md` support to our engineering team. Beyond the standard `SKILL.md`, we add `load-tools` and `suggested-tools` metadata so that skills can bring their tools with them. A `SKILL.md` might look like this:

```markdown title="review-pipeline/SKILL.md"
---
name: review-pipeline # (1)
description: Review the sales pipeline and identify deals that need follow-up.
load-tools: searchDeals getDealActivity # (2)
suggested-tools: getCompanyDetails # (3)
---

Find deals closing this quarter and check their recent activity before <!-- (4) -->
recommending a follow-up. Use ./references/sales-stages.md to interpret
each stage, then run ./scripts/build_report.py to generate the report. <!-- (5) -->
```

1. The name and description are all the agent sees at first: one line per skill, in every prompt.
2. When the agent loads the skill, these tools become callable right away.
3. These become findable through tool search, without being loaded.
4. The instructions enter the agent's context only when it loads the skill.
5. References and scripts stay on the filesystem until the agent reads or runs them.

<Sidenote n={2}>Breeze Assistant is HubSpot's AI assistant, built into the product for our customers.</Sidenote>

The agent loads these skills as needed. Structuring capabilities in this way has been a massive productivity boost for our engineering teams working on flagship agents like Breeze Assistant<Ref n={2} />. This approach allows us to break down capabilities into independent skills that teams can own, evaluate, and roll out. Indeed, Breeze Assistant today uses only a very minimal embedded tool set, instead relying on a set of curated skills to dynamically load its required functionality.

One of the most useful features of skills, however, is their ability to embed code and scripts, and to enable that we need to go one step further and give our agents a code execution environment.

### Giving agents computers

<Sidenote n={3}>We also have "real" microVMs for agents that need them, but most agents use Aviator's embedded execution environment, since it avoids external dependencies and the wait to spin up a VM.</Sidenote>

Aviator can give any agent a "computer" by way of an embedded Python environment through [Boomslang](https://github.com/HubSpot/boomslang), as well as a sandboxed Bash environment, both running in WASM<Ref n={3} />. That lets the sandbox ship inside the Aviator Java library. Agents that execute code need no external dependencies. The sandbox is also secure by default: code can only reach the few egress points we define. And it starts quickly enough that we can spin up tens of thousands of short-lived environments across our agents.

<Sidenote n={4}>The context layer is a shared set of files describing a customer's business, such as their ideal customer profiles and brand voice, that any agent can read.</Sidenote>

To make this environment useful, we also provide the agent with a virtual filesystem. Through this filesystem, agents are given access to CRM data, HubSpot's context layer<Ref n={4} />, skills and more.

<Sidenote n={5}>Breeze Engine is the runtime that hosts HubSpot's customer-facing agents, including Breeze Assistant. It is built on Aviator.</Sidenote>

On Breeze Engine<Ref n={5} />, an agent's filesystem looks like this by default:

```text caption="An example of a virtualized filesystem provided to an agent in Aviator."
/
├── work/                      read-write   scratch space for this conversation
├── skills/                    read-only    the skills this agent can load
│   └── review-pipeline/
│       ├── SKILL.md
│       └── scripts/build_report.py
├── context/                   read-only    fetched on first read
│   ├── index.md                            a manifest of everything below
│   ├── foundation/                         HubSpot's context layer
│   │   ├── company/icps.md
│   │   ├── brand/voice.md
│   │   └── user/README.md
│   └── agent/<agent-id>/                   context the agent's own team supplies
├── memories/                  read-write   what the agent remembers across conversations
├── artifacts/                 read-write   documents the agent produces for the user
├── uploads/                   read-only    files the user attached
└── tmp/                       read-write
```

Those files can come from an API, live in memory, or persist across conversations. We’ll dive more into our approach to filesystems in a future post!

## Aviator across HubSpot

Aviator now powers Breeze Assistant and agents across HubSpot's products and internal tools. Teams use it for everything from prospecting research, outreach, CRM insights, to code review, alert triage and more. Some agents interact directly with users; others run in the background, quietly executing on tasks. Sidekick Code, our cloud coding agent running on Aviator, now merges more than 2,500 pull requests a week.

<Chart
  type="lines"
  caption="Aviator adoption over time: production deployments using Aviator each week, December 2025 to September 2026. Counts omitted."
  y="Active deployments"
  numbers="hidden"
  xTicks="Jan 2026, Mar 2026, May 2026, Jul 2026, Sep 2026"
  values={false}
>{`
week, deployments
Dec 2025, 10
Dec 29 2025, 10
Jan 2026, 9
Jan 12 2026, 13
Jan 19 2026, 14
Jan 26 2026, 14
Feb 2026, 16
Feb 9 2026, 18
Feb 16 2026, 17
Feb 23 2026, 19
Mar 2026, 21
Mar 9 2026, 25
Mar 16 2026, 22
Mar 23 2026, 27
Mar 30 2026, 28
Apr 2026, 32
Apr 13 2026, 36
Apr 20 2026, 41
Apr 27 2026, 43
May 2026, 48
May 11 2026, 52
May 18 2026, 57
May 25 2026, 62
Jun 2026, 67
Jun 8 2026, 69
Jun 15 2026, 73
Jun 22 2026, 75
Jun 29 2026, 74
Jul 2026, 80
Jul 13 2026, 70
Jul 20 2026, 80
Jul 27 2026, 84
Aug 2026, 90
Aug 10 2026, 83
Aug 17 2026, 88
Aug 24 2026, 91
Aug 31 2026, 98
Sep 2026, 97
Sep 14 2026, 100
Sep 21 2026, 99
`}</Chart>

The teams building those agents own their prompts, tools, and product behavior. They share the runtime underneath. Adding a model provider, improving tool discovery, or extending the sandbox becomes work we can do once and make available across those applications.

We started with twenty lines of Java because we wanted building an agent to be an ordinary part of building a HubSpot service. The same idea has guided the rest of Aviator: let teams use the code and data they already have, enhanced with the power of agents.

This post has only scratched the surface of what Aviator can do, and there is a lot more we're excited to share. In future posts, we'll go deeper into the WASM runtimes, our virtualized filesystem implementation, how we write and manage agentic evals, and how we use tuning techniques to improve agents, tools, and skills automatically. Stay tuned!
