Cognition Methods

Capture your agent's reasoning — the why behind every action.

Cognition events are Tier 2 in the AOP spec. They are optional but provide the most valuable observability signal: an inside view of the agent's thought process.

thought()

Emits a cognition.thought event. Use this for free-form reasoning, chain-of-thought steps, or observations.

aop.thought(
  content: string,
  options?: {
    confidence?: 'high' | 'medium' | 'low'
    metadata?: Record<string, unknown>
  }
): void

Example

await aop.thought(
  'The user asked for Q1 data but the API only has monthly endpoints. I will need to make 3 separate calls and merge the results.',
  { confidence: 'high' }
)

await aop.thought(
  'Response from January endpoint looks malformed — trying alternate parser',
  { confidence: 'medium' }
)

goal()

Emits a cognition.goal event. Use this when the agent sets, updates, or completes a sub-goal.

aop.goal(
  goal: string,
  status: 'set' | 'in_progress' | 'completed' | 'abandoned',
  options?: {
    parentGoal?: string
    metadata?: Record<string, unknown>
  }
): void

Example

await aop.goal('Gather Q1 revenue data', 'set')
await aop.goal('Gather Q1 revenue data', 'in_progress')
// ... work ...
await aop.goal('Gather Q1 revenue data', 'completed')

// Nested goals
await aop.goal('Parse January data', 'set', {
  parentGoal: 'Gather Q1 revenue data'
})

decision()

Emits a cognition.decision event. Use this when the agent deliberately chooses between alternatives.

aop.decision(
  decision: string,
  options?: {
    alternatives?: string[]
    reasoning?: string
    metadata?: Record<string, unknown>
  }
): void

Example

await aop.decision('Use the REST API instead of GraphQL', {
  alternatives: ['REST API', 'GraphQL API', 'CSV export'],
  reasoning: 'REST API has pagination support and returns structured JSON. GraphQL endpoint is rate-limited to 10 req/min.'
})

uncertainty()

Emits a cognition.uncertainty event. Use this when the agent is unsure, encounters ambiguity, or wants to flag a decision for human review.

aop.uncertainty(
  content: string,
  options?: {
    confidence?: 'high' | 'medium' | 'low'
    metadata?: Record<string, unknown>
  }
): void

Example

await aop.uncertainty(
  'The document mentions "net revenue" and "gross revenue" interchangeably. Using gross revenue but this may be incorrect.',
  { confidence: 'low' }
)

await aop.uncertainty(
  'API returned 200 but the response body is empty. Proceeding with cached data.',
  { confidence: 'medium' }
)
Uncertainty events are particularly valuable for audit trails. They mark the exact moments where the agent was unsure, making post-hoc review efficient.

Related