Skip to main content
Building effectively on HubSpot with AI starts with a few foundational concepts. On this page, you’ll learn about:
  • What an agent actually does when it take actions on your behalf
  • What context is, and how it shapes what you build
  • Ways to structure your project so your agent picks up where it left off, every session
  • How to keep your credentials safe when building on HubSpot
  • A few guiding principles for building thoughtfully with AI

​
Agents and LLMs

An is the AI model itself. It’s the part that understands your prompts and generates text. An agent is that same LLM paired with a harness: software that runs the LLM in a loop and gives it tools to take actions in the world, like reading files, running terminal commands, or calling APIs. This is the key difference between an agent and a plain chat interface: a plain LLM only produces text in response to your prompts. An agent can act on its own: it can observe a situation, take an action, process the result, and keep going until the task is done. The harness is what enables this. It intercepts the LLM’s responses, detects when the model wants to use a tool, executes it, and feeds the result back. Harnesses can also add capabilities beyond the LLM itself (like persistent memory across sessions), and because the harness and LLM are separate components, most harnesses support swapping between different LLM models.

The harness is what connects the LLM to all of the capabilities (system prompt, memory, tools) that make it an agent.

AI coding agents like Claude Code, Cursor, Windsurf, Antigravity, and GitHub Copilot are built on this model. You describe what to build and the harness gives the LLM the ability to act: reading your project files, writing code, running terminal commands, and iterating until the task is done.
HubSpot also provides built-in AI agents for specific tasks in HubSpot: enriching CRM data, researching prospects, handling support conversations, and more. These are centrally managed from a workspace called Agent Hub (BETA). As a developer, you can build agent tools that extend what agents in HubSpot can do, including connecting to your own services and data.

​
The context window

The AI context window is the maximum amount of data (measured in tokens) that an LLM can process as input at any single time. Think of it as the agent’s short-term memory. Every time you send a new message and the LLM generates a response, every time the agent reads a document, looks at an image, or opens a code file, it consumes more of that context window. When an agent comes close to filling its context window, it has to make room to keep working. Different tools handle this differently: some summarize earlier parts of the conversation (Claude Code calls this compaction), others silently drop older messages, and some stop with an error. In most cases, something is lost in the process, which can result in the agent producing worse output. Check your tool’s documentation for how it handles a full context window. To keep your agent’s context clean:
  • Start fresh sessions for each new feature you’re working on. A long conversation where you’re asking the agent to add many features and configure many things at once can result in the context window getting bloated and the agent losing finer details that degrade the quality of its output.
  • If your agent supports it, you can also clear the agent’s context manually instead of spinning up a new agent or chat. Aside from clearing between new feature development, this can also be particularly helpful when an agent gets stuck in logic loops or continuously hits dead ends and failed attempts. If you’re using Claude Code, you can run /clear to reset the context without starting a new session.
To help fresh sessions pick up on work faster, it’s helpful to keep a running set of context files that anchor agents to your project. This is where spec-driven development can help streamline your workflow, as fresh agents can review your spec files to better understand what’s been done, what’s still in-progress, and what’s up next. It also helps to have the agent plan before it starts building. The context window defines the limit. What you load into it determines how well the agent can perform.

​
Types of context

For an agent to produce the highest quality results, it should have three important pieces of context:

Business context

The goals behind your desired solution: what is the business problem you’re solving, and who is going to use what you’re building.Business context often makes sense to include in your initial prompts, since the why behind the feature you’re asking AI to implement is important to the feature itself.

Systems context

Your company’s way of working, the tools outside of the platform you’re building on, the processes you follow, and the ways you want the agent itself to operate.Systems context is what you add to agent skills and your agent instructions file that lives in your code repository. This is where you explain to the agent how you like to work.

Platform context

The tech stack, the APIs, the frameworks for building what you’re creating. If you’re building UI extensions, it’s everything to do with the way UI extensions work, what UI components are available, and how they interact with the CRM.This is where the local Developer MCP server helps significantly. It gives your agent the ability to search and read HubSpot’s developer documentation in markdown rather than the full HTML you see in a browser, so the agent gets just what it needs, when it needs it.
For practical guidance on how to give your agent the right context at the start of each session, see Give the agent the right context.

​
Your agent instructions file

Most AI coding agents support a file that lives in your project and gives the agent standing instructions, such as how you like to work, what conventions to follow, and what context it should always have. Every new session reads this file automatically, so you don’t need to re-explain your preferences each time. These files are what makes instructions stick across sessions, and is something you can build on over time as a project grows. When creating a new HubSpot project using the hs project create or hs get-started commands, HubSpot automatically includes its own set of agent context files when you create a new local project. These give agents an informed starting point before writing any code.

​
Spec-driven development

Spec-driven development is a way of structuring your project that helps each agent session start informed. The idea is to maintain markdown files in your project that describe what you’re building and how it works, including the goals, the features, the data model, and the user experience. These files become the source of truth for the project, something the agent reads at the start of each session rather than piecing together from the code itself.

This is particularly useful for multi-session projects. Each new agent session starts with an empty context window and no memory of previous work. Spec files give the agent a high-level picture of the project from the start, so it can pick up where the last session left off without needing you to re-explain everything.

my-hubspot-project
hsproject.json
AGENTS.md
specs
overview.md
features.md
data-model.md
user-experience.md
In spec-driven development you typically collaborate with the agent to write a high-level description of what you’re building and why, what features it has, how they work, and what the user experience is like. Once you have those initial documents, you have the coding agent create the actual project and continuously add deeper detail to your specification files as you iterate. Some benefits of this approach:
  • Documentation of a code project is typically the last thing to get updated, and people working on the project end up with institutional knowledge that never gets communicated out. This problem is worse if the code was AI-generated, because it’s possible the human that generated it doesn’t fully understand it. Spec-driven development reduces the extent of this problem by ensuring there’s a human-readable explanation of what the software does.
  • When iterating on a project, instead of loading the full codebase into the agent’s context window you can load the spec documents instead, giving it a high-level understanding of how the application is built. The agent can then discover the pieces of the codebase one by one until it finds the files it needs to work on.
Some possible downsides:
  • The agent can make assumptions about how something is implemented in another part of the codebase based on the specs.
  • The codebase and the specification documents can become out of sync, which can confuse both humans and AI.
  • The agent sometimes ends up needing to load the full codebase anyway, which can mean wasted tokens.
Spec-driven development is likely a good strategy if you don’t know how to read and write the code yourself. It leads to in-codebase documentation that any developer who inherits the project can use to quickly understand it.

​
Secrets and security

Secrets are authentication credentials such as API keys and access tokens, that grant the ability to act on your behalf for various functions like retrieving, updating, or deleting data. Secrets should never be shared or exposed because it risks compromising your account on whichever platform the secret gives access to. When you type into a coding agent’s chat interface, that input is sent to the LLM provider’s servers. Pasting a secret into your prompt, instructions file, or any project file the agent reads sends that value to those servers as well. To safely provide authentication credentials when building on HubSpot, you can use the HubSpot CLI secret manager to store them securely:
HubSpot stores the value on its backend servers. In your code, it gets referenced only as the name of the secret (process.env.SECRET_NAME), not the value itself. For private app access tokens specifically, HubSpot provides PRIVATE_APP_ACCESS_TOKEN automatically in every serverless function with no setup required. This means you never need to copy your app’s access token out of HubSpot and paste it anywhere. For the full set of CLI commands, see managing secrets.

​
Solve for your customer, not token count

It can be tempting to treat the volume of LLM tokens processed as a measure of productivity, but generating a high volume of text is not the same as making progress. Your real goal is to empower the end user of your project, save them time, and make a process that was once complex easier. At HubSpot we call this solving for the customer. In your company, the “customer” might be your teammates, but the goal is the same.

​
Integrate LLMs where they provide value over traditional code

If you’re planning to use an AI API to integrate an LLM into your project, first consider whether more traditional code might actually solve the problem better. Keep in mind that every cloud AI request has a cost, AI-generated output can contain errors, and AI can produce plausible-sounding but incorrect information. Traditional logic-based programming (“if this then that”) is reliable, testable, typically more responsive, and predictable. You can also combine both approaches, using each for what it does best. For example, if you’re displaying a set of data that needs categorization based on unstructured values (say, customer feedback that needs to be labeled positive or negative), an LLM can categorize that feedback by reading the text. But the actual display of the feedback you’d handle through traditional logic-based code.
Last modified on September 9, 2026