Sessions & References

Sessions enable multi-turn conversations where users can reference previous results naturally.

The Problem

Without sessions, every Trik call is isolated:


User: Search for AI articles
Agent: Found 3 articles.

User: Show me the second one
Agent: Which article? I don't know what you searched for.

With sessions:


User: Search for AI articles
Agent: Found 3 articles about AI.

User: Show me the second one
Agent: (resolves "the second one" using session history)

How Sessions Work

1. Enable in Manifest


{
  "capabilities": {
    "session": {
      "enabled": true,
      "maxDurationMs": 1800000,
      "maxHistoryEntries": 10
    }
  }
}

Field	Description
`enabled`	Turn sessions on/off
`maxDurationMs`	Session timeout (default: 30 min)
`maxHistoryEntries`	Max stored entries

2. Session ID Flow

The gateway manages session IDs automatically:


Request 1: { sessionId: null, action: "search", input: { topic: "AI" } }
Response 1: { sessionId: "sess_abc123", agentData: { count: 3 } }

Request 2: { sessionId: "sess_abc123", action: "details", input: { reference: "the second one" } }
Response 2: { sessionId: "sess_abc123", userContent: { ... } }

3. History Storage

Your Trik can store relevant data in the session:


// In your graph execution
context.session.addEntry({
  action: "search",
  input: { topic: "AI" },
  result: {
    articleIds: ["art-001", "art-002", "art-003"],
    topic: "AI"
  }
});

Reference Resolution

Users naturally refer to previous results:

“the second one”
“the healthcare article”
“that last thing”
“the one about neural networks”

Your Trik resolves these using session history:


function resolveReference(reference: string, session: Session): string | null {
  const lastSearch = session.getLastEntry("search");
  if (!lastSearch) return null;
 
  const { articleIds, articles } = lastSearch.result;
 
  // Ordinal reference: "the second one"
  const ordinal = parseOrdinal(reference);
  if (ordinal && articleIds[ordinal - 1]) {
    return articleIds[ordinal - 1];
  }
 
  // Semantic reference: "the healthcare one"
  for (const article of articles) {
    if (matchesTopic(article, reference)) {
      return article.id;
    }
  }
 
  return null;
}

Example: Article Search

The article-search demo Trik shows this pattern:

Search Action (Template Mode)


{
  "action": "search",
  "input": { "topic": "AI" }
}

Stores in session:


{
  "action": "search",
  "result": {
    "articleIds": ["art-001", "art-002", "art-003"],
    "articles": [
      { "id": "art-001", "title": "AI in Healthcare", "topic": "health" },
      { "id": "art-002", "title": "Neural Networks 101", "topic": "AI" },
      { "id": "art-003", "title": "Machine Learning Trends", "topic": "AI" }
    ]
  }
}

Details Action (Passthrough Mode)


{
  "action": "details",
  "input": { "reference": "the healthcare one" }
}

Resolves “the healthcare one” to art-001 using session history.

Session Patterns

Pattern 1: Store IDs, Not Content


// Good: store references
session.addEntry({
  action: "search",
  result: { articleIds: ["a1", "a2", "a3"] }
});
 
// Bad: store full content (memory waste + security risk)
session.addEntry({
  action: "search",
  result: { articles: [{ fullText: "..." }] }
});

Pattern 2: Store Metadata for Resolution


session.addEntry({
  action: "search",
  result: {
    articleIds: ["a1", "a2"],
    metadata: {
      // Enough info to resolve references
      "a1": { title: "AI in Healthcare", topics: ["AI", "health"] },
      "a2": { title: "Neural Networks", topics: ["AI", "ML"] }
    }
  }
});

Pattern 3: Fallback to Last Results

When no specific reference is given, use the last search:


function getArticleIds(input, session): string[] {
  // Explicit IDs provided
  if (input.articleIds?.length) {
    return input.articleIds;
  }
 
  // Use last search results
  const lastSearch = session.getLastEntry("search");
  if (lastSearch?.result?.articleIds) {
    return lastSearch.result.articleIds;
  }
 
  return [];
}

Session Lifecycle


┌─────────────────────────────────────────────┐
│ Session Created                              │
│ First request with session.enabled = true   │
└─────────────────┬───────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────┐
│ Session Active                               │
│ Subsequent requests include sessionId       │
│ History accumulates up to maxHistoryEntries │
└─────────────────┬───────────────────────────┘
                  │
        ┌─────────┴─────────┐
        ▼                   ▼
┌───────────────┐  ┌────────────────────┐
│ Timeout       │  │ Max entries reached│
│ (maxDuration) │  │ (oldest removed)   │
└───────┬───────┘  └────────────────────┘
        │
        ▼
┌─────────────────────────────────────────────┐
│ Session Expired                              │
│ Next request creates new session            │
└─────────────────────────────────────────────┘

Testing Sessions

Include session behavior in your tests:


it("resolves ordinal references", async () => {
  // First call: search
  const searchResult = await trik.execute({
    action: "search",
    input: { topic: "AI" }
  });
  const sessionId = searchResult.sessionId;
 
  // Second call: get details by reference
  const detailsResult = await trik.execute({
    sessionId,
    action: "details",
    input: { reference: "the second one" }
  });
 
  expect(detailsResult.userContent.metadata.articleId).toBe("art-002");
});

Next: Learn how to use Triks in your projects.