---
title: Intent
description: "Goals and gaps. What your agent is trying to do and what it does not know."
---

## What Intent Is

Intent is what your agent is *trying to accomplish*, as opposed to what it *understands to be true*. It covers goals, gaps, decisions, and constraints: the preferences and rules that shape what the agent pursues.

"Map the competitive landscape" is intent: it expresses a direction, not a fact. "The market is $4.2B" is a belief: it can be supported or refuted by evidence.

The SDK keeps these separate because they serve different purposes.

## Goals

Goals drive action selection. They tell the system what questions to answer and what gaps to fill.

```ts
await beliefs.add('Map the competitive landscape', { type: 'goal' })
await beliefs.add('Identify top 3 market opportunities', { type: 'goal' })
```

An unmet goal reduces clarity, signaling to the agent that more investigation is needed before acting. Goals accumulate context but do not participate in the confidence system. An agent pursuing a hypothesis shouldn't grow more confident in it just because it's pursuing it.

## Gaps

Gaps represent missing information: what the agent has not investigated or cannot answer yet.

```ts
await beliefs.add('No data on enterprise pricing models', { type: 'gap' })
await beliefs.add('Missing APAC market analysis', { type: 'gap' })
```

Gaps are first-class in the belief system because they drive the next research action. An agent that knows what it does not know can prioritize its work.

Gaps penalize the [clarity](/dev/core/clarity) score. High-impact gaps, those with many downstream dependencies, penalize it more. The system naturally prioritizes filling the most important gaps first.

### Resolving Gaps

When the agent has addressed a gap, mark it resolved:

```ts
await beliefs.resolve('Missing APAC market analysis')
```

Resolved gaps stop penalizing clarity and update the world state.

## The Is/Ought Firewall

Factual evidence updates beliefs. Normative information (preferences, goals, desires) does not.

| Input | Type | Effect |
|-------|------|--------|
| "The TAM is $5B" | Factual | Updates the market size belief |
| "I want to target enterprise" | Normative | Recorded as a goal |
| "We must support SOC2" | Normative | Recorded as a constraint |
| "Gartner reports 34% growth" | Factual | Updates the growth rate belief |

This prevents a common failure mode: a user's strong preference inflating factual confidence. Without the firewall, the more a user says "I want X," the more confident the system becomes that X is the right answer, regardless of what the evidence shows.

<Callout type="warning" title="The firewall">
Preferences do not update factual beliefs. Without this separation, a user repeating "I want X" would gradually inflate the agent's confidence that X is *true*: preferences masquerading as evidence. The firewall keeps factual claims and normative intent on separate tracks, so user conviction can't distort the belief state.
</Callout>

## Reading Intent

Goals and gaps are returned from `beliefs.read()`:

```ts
const world = await beliefs.read()

console.log(world.goals) // ['Map the competitive landscape']
console.log(world.gaps)  // ['Missing APAC market analysis']
```

They are also included in `beliefs.before()` context, so the agent sees its current goals and open gaps at the start of each turn.

<CardGroup cols={2}>
  <DocsCard title="Clarity" description="How gaps affect the clarity score." href="/dev/core/clarity" />
  <DocsCard title="Patterns" description="Gap-driven research and other common patterns." href="/dev/sdk/patterns" />
</CardGroup>