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.
1await beliefs.add('Map the competitive landscape', { type: 'goal' })
2await 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.
1await beliefs.add('No data on enterprise pricing models', { type: 'gap' })
2await 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 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:
1await 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.
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.
Reading Intent
Goals and gaps are returned from beliefs.read():
1const world = await beliefs.read()
2
3console.log(world.goals) // ['Map the competitive landscape']
4console.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.