What Intent Is
Intent is what your agent is trying to accomplish. It captures goals, gaps, decisions, and constraints: the normative layer that drives behavior.
"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 creates pressure to investigate. Goals accumulate context but do not participate in the confidence system. An agent pursuing a hypothesis should not grow more confident in it just because it is 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. This prevents strong opinions from masquerading as strong evidence.
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.