Interactive Sessions

Some businesses offer dynamic capabilities — interactive multi-turn conversations powered by AI. Instead of a simple link, your users can get quotes, book appointments, compare plans, or fill out applications directly through your agent.

How sessions work

1. Search returns a result with type: 'dynamic_capability'
2. Initiate a session — billing event is triggered
3. Exchange messages — your user talks to the business agent
4. End the session — get a summary of what was accomplished

Full example

import { PenguinClient } from 'penguin-sdk';

const client = new PenguinClient({ apiKey: 'am_live_...' });

// 1. Search for capabilities
const results = await client.search({
  query: 'I need a moving quote for a 2-bedroom apartment',
});

// 2. Find a dynamic capability
const dynamicCap = results.capabilities.find(c => c.type === 'dynamic_capability');
if (!dynamicCap) {
  console.log('No interactive sessions available');
  return;
}

// 3. Start the session
const session = await client.sessions.initiate({
  capability_id: dynamicCap.capability_id,
  ad_unit_id: dynamicCap.ad_unit_id,
  clearing_price_cents: dynamicCap.clearing_price_cents,
});

console.log('Agent:', session.message);
console.log('Session ID:', session.session_id);

// 4. Continue the conversation
const reply = await client.sessions.sendMessage({
  session_id: session.session_id,
  message: 'Moving from Toronto to Vancouver, approximately 800 sq ft',
});

console.log('Agent:', reply.message);
console.log('Collected data:', reply.structured_data);
console.log('Still need:', reply.pending_fields);

// 5. End when done
const summary = await client.sessions.end({
  session_id: session.session_id,
});

console.log('Summary:', summary.summary);
console.log('Messages:', summary.message_count);

Session limits

Limit	Value
Max messages per session	50
Max tokens per session	100,000
Max cost per session	$5.00
Session expiry	60 minutes

GitHub integration

Sessions can connect to GitHub repos for code-aware business conversations:

const result = await client.sessions.connectGitHub({
  session_id: session.session_id,
  repo: 'owner/repo',
});

if (result.auth_required) {
  // User needs to authorize GitHub access
  console.log('Please visit:', result.auth_url);
} else {
  console.log('Connected:', result.message);
}

Structured data extraction

During a session, the business agent automatically extracts structured data from the conversation (names, addresses, preferences, etc.). You can access this via response.structured_data and track what fields are still needed via response.pending_fields.

You can also pre-fill data when starting a session:

const session = await client.sessions.initiate({
  capability_id: cap.capability_id,
  ad_unit_id: cap.ad_unit_id,
  clearing_price_cents: cap.clearing_price_cents,
  initial_data: {
    name: 'Jane Doe',
    email: 'jane@example.com',
    location: 'Toronto, ON',
  },
});