Agent Insights

As the agent talks to a user over time, it builds up a derived view of who they are — what they care about, what they're working toward, who's in their life, and how their mood trends. Agent Insights exposes that derived state as readable (and for some signals, writable) endpoints. These are not things you author; the context engine extracts them automatically from conversations.

What you can build with it

• Personalized dashboards — show the user exactly what the agent has learned about them, building transparency and trust
• Weekly wrap-ups — "here's what's on your mind this week" compiled from diary entries and top interests
• Relationship-aware UX — surface the list of people the agent knows about so users can review or correct them
• Goal-tracking integrations — sync agent-tracked goals to external task managers or CRMs after they are detected
• Engagement health scoring — aggregate breakthroughs, mood trend, and habit streaks into a single user health metric

Quickstart

Fetch habits, goals, and interests for a user in one pass.

import { Sonzai } from "@sonzai-labs/agents";

const client = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });

const agentId = "agent_abc";
const userId  = "user_123";

const [habits, goals, interests] = await Promise.all([
client.agents.listHabits(agentId, { userId }),
client.agents.listGoals(agentId, { userId }),
client.agents.getInterests(agentId, { userId }),
]);

console.log("habits:",    habits.habits.length);
console.log("goals:",     goals.goals.length);
console.log("interests:", interests.interests.length);

Core concepts

Derived, not authored. These signals are extracted from conversation text by the context engine. You do not push them in; the agent surfaces them automatically as it talks.

Per-instance scoping. Pass instanceId (TS/Python) or instanceID (Go) to filter results to a specific agent instance — useful when an agent is deployed in multiple scenarios or chat contexts for the same user.

Write endpoints for some signals. Goals and habits can be explicitly created, updated, or deleted when your application needs to drive a specific state (e.g., seeding a goal when a user starts onboarding, or marking a goal achieved after a purchase event). Interests, relationships, diary, constellation, and breakthroughs are read-only.

Read latency. Derived signals update at conversation turn-end, not in real time during a turn. Reads immediately after a chat call may not yet reflect the latest turn.

Full API

Read endpoints

Write endpoints (goals and habits)

Goals and habits support full CRUD. All other insight types are read-only.

Habits

Habits are recurring behaviors the context engine detects across conversations — things like "user meditates in the morning" or "user reviews their tasks every Sunday." Each habit has a strength (0-1) that rises with observations and a formed flag that is set once the habit is considered stable.

const habits = await client.agents.listHabits("agent_abc", {
userId: "user_123",
});

for (const h of habits.habits) {
console.log(h.name, h.category, h.strength, h.formed);
}

Goals

Goals represent what the user is working toward. They are extracted automatically from conversation intent — "I want to run a 5K by June" becomes a goal with a type, title, and priority. Goals have a status field: active, achieved, or abandoned.

// Read
const goals = await client.agents.listGoals("agent_abc", { userId: "user_123" });
for (const g of goals.goals) {
console.log(g.title, g.status, g.priority);
}

// Seed a goal for a new workflow
const goal = await client.agents.createGoal("agent_abc", {
userId:      "user_123",
title:       "Complete onboarding",
description: "Finish all onboarding steps",
type:        "task",
priority:    1,
});

// Mark achieved after a business event
await client.agents.updateGoal("agent_abc", goal.goal_id, {
userId: "user_123",
status: "achieved",
});

Interests

Interests are topics and themes the context engine identifies as meaningful to the user — things like "machine learning", "hiking", or "Italian cooking." Unlike goals, interests have no lifecycle status; they accumulate over time.

const interests = await client.agents.getInterests("agent_abc", {
userId: "user_123",
});

for (const i of interests.interests) {
console.log(i.topic, i.category);
}

Relationships

Relationships are the people the user mentions across conversations — friends, family, colleagues, and others the agent has learned about. Each entry includes the person's name, their relationship to the user, and any context the agent has collected.

const rel = await client.agents.getRelationships("agent_abc", {
userId: "user_123",
});

for (const r of rel.relationships) {
console.log(r.name, r.relationship_type, r.context);
}

Diary

The diary contains agent-authored entries written at session end — reflections on what happened, what was learned, and how the relationship is evolving. Each entry is anchored to a session and a timestamp. Diary entries are the richest narrative signal available.

const diary = await client.agents.getDiary("agent_abc", {
userId: "user_123",
});

for (const entry of diary.entries) {
console.log(entry.created_at, entry.content);
}

Constellation

The constellation is the agent's knowledge graph for a user — a set of nodes (concepts, people, themes) and edges (relationships between them) that the context engine builds from recurring patterns across memory. Nodes have a significance score and a node_type.

const c = await client.agents.getConstellation("agent_abc", {
userId: "user_123",
});

for (const node of c.nodes) {
console.log(node.label, node.node_type, node.significance);
}

Breakthroughs

Breakthroughs are significant relationship or emotional milestones detected by the platform — moments where the agent's understanding of the user meaningfully deepened, or where a notable shift in the relationship dynamic was recorded.

const bt = await client.agents.listBreakthroughs("agent_abc", {
userId: "user_123",
});

for (const b of bt.items) {
console.log(b.type, b.description, b.timestamp);
}

Combines with other features

With Memory — insights are summaries over raw facts

Insight signals are derived summaries; the underlying evidence lives in memory. Fetch habits to learn what patterns exist, then use memory.search to pull the raw conversation facts behind one of them.

const habits = await client.agents.listHabits("agent_abc", { userId: "user_123" });
const topHabit = habits.habits[0];

// Find the raw memories that support this habit
const facts = await client.agents.memory.search("agent_abc", {
userId: "user_123",
query:  topHabit.name,
limit:  10,
});

console.log(`Found ${facts.results.length} facts supporting "${topHabit.name}"`);

With Emotions — mood + insights for a full user picture

getMood and these insight endpoints together form the agent's complete understanding of a user at a point in time. Fetch both to power a user-facing "how the agent sees you" view or a support dashboard.

const [mood, goals, diary] = await Promise.all([
client.agents.getMood("agent_abc", { userId: "user_123" }),
client.agents.listGoals("agent_abc", { userId: "user_123" }),
client.agents.getDiary("agent_abc", { userId: "user_123" }),
]);

console.log("Current mood:", mood.label);
console.log("Active goals:", goals.goals.filter(g => g.status === "active").length);
console.log("Diary entries:", diary.entries.length);

With Advance Time — replay insight formation

Advance Time fast-forwards the context engine's processing — generating new diary entries, decaying mood, and updating derived signals — without waiting real time. This is useful for simulating what the agent would know after a period of elapsed time, and for testing insight endpoints against a populated state.

// Advance 7 days to populate diary entries and update insights
const result = await client.workbench.advanceTime({
  agentId: "agent_abc",
  userId:  "user_123",
  simulatedHours: 168,
});

// Now read the insights that formed during that window
const diary = await client.agents.getDiary("agent_abc", { userId: "user_123" });
console.log("Diary entries after 7d:", diary.entries.length);

Tutorials

• Memory — the raw facts behind insights; use memory.search to drill into any signal
• Emotions — mood, mood history, and aggregate mood statistics
• Personality — Big5 traits and personality evolution (a different kind of derived state)
• Advance Time — fast-forward the agent's processing to simulate elapsed time