Building custom Agent Tools for Breeze: what the architecture actually looks like and where it break

Develop, Build & Integrate APIs & Integrations
,
1

After spending some time working with the Agent Tools reference and creating some Agent Tools myself for Breeze agents, I felt that sharing some of my learnings around the actual implementation would be valuable because while the documentation provides information about the components, it does not give a good overview of how they all play together and where the usual failure points are.

What Agent Tools are really

Agent Tools are custom workflow actions that have a flag making them accessible in the Breeze agent context. They are not an additional integration layer – they are built using the Developer Projects framework (minimum version v2025.2, preferred v2026.03), reviewed, and published through the app listing.

The agent invokes the tool the same way as any custom code action is invoked from a workflow – by making an HTTPS request to the tool’s actionURL with its input parameters. Your server handles the request and returns the output. Based on the output, the agent reasons further.

The restriction that catches developers

Once you declare an inputField as required and submit the project, you cannot change it or update it anymore. It is mentioned in the reference, but it’s very easy to overlook it when developing iteratively. Once the field is declared as required, any workflow and agent that has already used the tool will break if the schema is changed.

Develop with all fields marked as non-required. Only declare required=true on a field once it is certain that the field name, type, and label will not change anymore.

The authentication difference

For Agent Tools within a public app, authentication is done via your app’s OAuth configuration in app-hsmeta.json, not a separate token. Upon invoking your tool via Breeze, HubSpot supplies your tool with authentication information through the request payload. Unlike the direct API calls to HubSpot, this authentication approach may surprise the developers trying to configure their own token management system.

The approval layer

The “Review before running this tool” toggle within Breeze Studio is the component that allows approving CRM writes prior to committing. It is the governance control making AI agent automation auditable for the sake of regulated industries or sensitive workflows. Not a debug utility, it is rather an enterprise deployment feature. Good to know in advance when you plan on selling AI agent deliverables to compliance-minded clients.

The submission process

Agent Tools undergo the same app review process as all the other features on the Marketplace. Make sure to allocate time for that review process before hoping that your tool will be ready for use in client’s portal. Developing and testing on your own developer account is good enough, but going GA for the paying clients means that your app needs to be certified.

Has anyone here ever used Agent Tools in production? Would love to hear about anyone’s experience in terms of running into the inputField lock constraint during their project.

3

Hey @SamuelOliver, Yes, I’ve worked with Agent Tools in production, and the inputField constraint is definitely one of the things I’d flag early.

A few lessons from my side:

  • I treat the input schema as version-locked once it’s published.

  • During development, I keep fields non-required until the structure is genuinely final.

  • I test the agent > tool > workflow > HubSpot response flow end-to-end, rather than validating the tool in isolation.

  • For production, I also plan the Marketplace review into the timeline from day one.

The biggest takeaway for me has been: design the tool contract first, then build around it. It saves a lot of rework later.

Great write-up, especially the distinction between the approval layer and debugging. That’s an easy one to misunderstand.

5

Thanks for that. I totally agree that the tool contract is stable once it’s published.

There is one thing I am interested to know: When you had to evolve your tool contract after publishing it into production, did you version it as a different tool or was it possible to evolve the schema in such a way that the behavior of the agent was not broken?

6

Thank you for sharing this information. It is quite clear why action versioning should be used as the contract is immutable.

As far as timeout issues are concerned, have you gone the route of putting long tasks on an asynchronous queue with callbacks, or have you managed to keep the majority of actions performed by the Agent Tools within the window defined by Breeze?

7

I’ve preferred treating a published tool contract as immutable rather than trying to evolve the existing schema in place.

When I needed to introduce a meaningful change, I kept the existing tool stable and treated the new contract as a separate version/tool. That gave me much more control over existing workflows and agent behavior.

For smaller changes, I’ve had better results adding optional fields and keeping the existing inputs/outputs backward-compatible rather than renaming or removing anything.

My rule of thumb has been: if an existing agent could interpret the request differently after the schema change, I’d version it rather than risk breaking production behavior.

8

That is how I have thought as well. Versioning becomes very safe once the agents start depending on the contract itself.

I am interested in knowing whether you have come across situations when you had more than one version of the tool deployed in production? If yes, how did you decide to stop using the old version without interrupting the work?

10

I’ve had cases where the older version needed to stay live while the newer contract was being validated, so I treated the migration as a controlled transition rather than a hard cutover.

My approach was pretty simple:

  • Keep the old version available for existing agents.

  • Deploy and test the new version independently.

  • Move agents over in batches rather than all at once.

  • Monitor failures and outputs before retiring the old version.

  • Only deprecate the old tool once nothing production-critical is still depending on it.

The key for me was not making tool retirement part of the release itself. I treated it as a separate migration step. That gave us a safe rollback path if anything behaved differently once the agent was actually reasoning against the new contract.

That separation between releasing a new version and retiring the old one has probably been the most useful lesson from working with these in production.

11

That is indeed a good approach for differentiating between deployment risks and migration risks. One question that comes to mind: How did you figure out what agents were using the legacy system during the transition period? Did you depend on the telemetry of the agents or did you have some kind of inventory beforehand?

12

Mostly a combination of both. I kept an inventory of which agents/workflows were mapped to each tool version, and then used telemetry as the validation layer during the transition.

The inventory gave us the dependency map; telemetry helped catch anything we hadn’t accounted for, especially older agents that were still active.

For me, that combination was much safer than relying on telemetry alone. Know your dependencies first, then use runtime data to confirm them before deprecating the legacy version.

That has been the most reliable approach in production from my experience.

13

Thanks for sharing your strategy. The difference that you made between dependency mapping and runtime validation is awesome. Thanks a lot for taking the effort to explain the practical experience from your production environment.