Session Handoff

from dakera import DakeraClient

client = DakeraClient(base_url="http://localhost:3000", api_key="dk-...")


class HandoffSession:
    """A source session that ends with a structured handoff summary."""

    def __init__(self, agent_id: str, user_id: str, channel: str = "webchat"):
        self.agent_id = agent_id
        self.user_id = user_id
        self.channel = channel
        self.session_id = None
        self.attempted_resolutions = []

    def start(self) -> str:
        session = client.start_session(
            agent_id=self.agent_id,
            metadata={"user_id": self.user_id, "channel": self.channel},
        )
        self.session_id = session["id"]
        return self.session_id

    def store_event(self, content: str, event_type: str, importance: float = 0.75):
        """Store a conversation event bound to this session."""
        return client.store_memory(
            agent_id=self.agent_id,
            content=content,
            importance=importance,
            session_id=self.session_id,
            tags=["event", event_type],
        )

    def record_attempt(self, action: str, outcome: str):
        record = f"Tried: {action}. Outcome: {outcome}."
        self.attempted_resolutions.append(record)
        return self.store_event(record, "attempted-resolution", importance=0.7)

    def handoff(self, target_agent: str, reason: str, sentiment: str,
                user_goal: str, recommended_action: str, urgency: str = "normal") -> dict:
        """1. Store the summary at importance 1.0  2. End the session."""
        attempts = " ".join(self.attempted_resolutions) or "No prior attempts."
        summary = client.store_memory(
            agent_id=self.agent_id,
            content=(f"HANDOFF SUMMARY [{urgency.upper()}]: User goal: {user_goal}. "
                     f"Situation: {attempts} User sentiment: {sentiment}. "
                     f"Recommended next action: {recommended_action}."),
            importance=1.0,
            session_id=self.session_id,
            tags=["handoff", "session-summary", f"priority:{urgency}"],
            metadata={"handoff_to": target_agent, "escalation_reason": reason, "urgency": urgency},
        )
        client.end_session(self.session_id, summary=f"Escalated to {target_agent}: {reason}")
        return {"source_session_id": self.session_id, "handoff_memory_id": summary["id"],
                "target_agent": target_agent, "urgency": urgency}


class IncomingSession:
    """Target agent session: loads the handoff context before saying anything."""

    def __init__(self, agent_id: str, handler_id: str, handoff_data: dict):
        self.agent_id = agent_id
        self.handler_id = handler_id
        self.source = handoff_data["source_session_id"]

    def start_and_load_context(self, query: str, top_k: int = 8):
        client.start_session(
            agent_id=self.agent_id,
            metadata={"handler": self.handler_id, "handoff_from": self.source, "channel": "webchat"},
        )
        # The summary first, by tag; then the rest of the source session
        summary = client.recall(agent_id=self.agent_id, query=query,
                                tags=["handoff"], session_id=self.source, top_k=1).memories
        rest = client.recall(agent_id=self.agent_id, query=query,
                             session_id=self.source, top_k=top_k).memories
        seen = {m.id for m in summary}
        return summary + [m for m in rest if m.id not in seen]

    @staticmethod
    def opening_message(context) -> str:
        if context and context[0].content.startswith("HANDOFF SUMMARY"):
            return ("I've just been briefed on your situation and I have the full context "
                    "from your previous conversation. Let me take it from here.")
        return "How can I help you today?"


# ===== USAGE: Customer Support Escalation =====
bot = HandoffSession(agent_id="support-bot", user_id="user-u_9k3m")
bot.start()
bot.store_event("User: Maria Santos reports unauthorized charge $89.99 on Jan 15. Transaction: TXN-88291.",
                event_type="issue-report", importance=0.85)
bot.record_attempt("Standard refund flow for TXN-88291", "FAILED: transaction exceeds 30-day refund window")
bot.record_attempt("Offered $90 account credit as alternative", "REJECTED: user insists on full refund only")
bot.store_event("User expressed frustration: 'This is the third time I am calling about this.'",
                event_type="sentiment", importance=0.85)

handoff_data = bot.handoff(
    target_agent="human-agent",
    reason="refund-window-exceeded-supervisor-required",
    sentiment="High frustration: 3rd contact, previous resolution attempts failed",
    user_goal="Full refund of $89.99 unauthorized charge TXN-88291",
    recommended_action="Supervisor override refund. Mention 5-min ETA already committed.",
    urgency="high",
)

human = IncomingSession(agent_id="support-bot", handler_id="agent-sarah", handoff_data=handoff_data)
context = human.start_and_load_context("billing dispute refund situation and what was tried")
for mem in context:
    print(f"  [{mem.importance:.2f}] {mem.content[:100]}")
print(IncomingSession.opening_message(context))

import { DakeraClient } from '@dakera-ai/dakera';

const client = new DakeraClient({ baseUrl: 'http://localhost:3000', apiKey: 'dk-...' });
const AGENT = 'support-bot';

// ===== SOURCE AGENT (Bot) =====

// 1. Start the bot session
const botSession = await client.startSession(AGENT, { user_id: 'user-u_9k3m', channel: 'webchat' });

// 2. Store context events during the conversation
await client.storeMemory(AGENT, {
  content: 'User Maria Santos disputes $89.99 charge TXN-88291 from Jan 15. Not authorized.',
  importance: 0.85,
  session_id: botSession.id,
  tags: ['billing', 'dispute', 'unauth-charge'],
});
await client.storeMemory(AGENT, {
  content: 'Standard refund flow failed: transaction exceeds 30-day window. Credit offer ($90) rejected.',
  importance: 0.75,
  session_id: botSession.id,
  tags: ['attempted-resolution', 'failed'],
});

// 3. Store the handoff summary at maximum importance
const { memory: summary } = await client.storeMemory(AGENT, {
  content: [
    'HANDOFF SUMMARY [HIGH]:',
    'User: Maria Santos (user-u_9k3m).',
    'Goal: Full refund of $89.99 unauthorized charge TXN-88291 (Jan 15).',
    'Tried: standard refund (30-day limit exceeded), credit offer (rejected).',
    'Sentiment: high frustration, 3rd contact.',
    'Committed: escalation within 5 minutes.',
    'Action: supervisor override refund required.',
  ].join(' '),
  importance: 1.0,
  session_id: botSession.id,
  tags: ['handoff', 'session-summary', 'priority:high'],
  metadata: { handoff_to: 'human-sarah', escalation_reason: 'refund-flow-failed' },
});

// 4. End the bot session (endSession sends a summary from dakera-js 0.12.2)
await client.endSession(botSession.id, { summary: 'Escalated to a human agent: refund flow failed.' });

// ===== TARGET AGENT (Human) =====

// 5. Start the human agent's session, linked to the original
await client.startSession(AGENT, { handler: 'human-sarah', handoff_from: botSession.id });

// 6. The summary first (tag filter), then the rest of the source session
const query = 'billing dispute refund situation attempted resolutions';
const first = await client.recall(AGENT, query, { tags: ['handoff'], session_id: botSession.id, top_k: 1 });
const rest = await client.recall(AGENT, query, { session_id: botSession.id, top_k: 8 });
const context = [...first.memories, ...rest.memories.filter(m => m.id !== summary.id)];

context.forEach(mem => console.log(`  [${mem.importance.toFixed(2)}] ${mem.content.substring(0, 100)}`));

// 7. The human agent acknowledges continuity
const opening = context[0]?.content.startsWith('HANDOFF SUMMARY')
  ? "I have the full context from your previous conversation. I'm going to resolve this for you now."
  : 'Let me pull up your case.';
console.log(`Agent opening: "${opening}"`);

use dakera_client::{DakeraClient, RecallRequest, StoreMemoryRequest};
use serde_json::json;

let client = DakeraClient::builder("http://localhost:3000").api_key("dk-...").build()?;
let agent = "support-bot";

// ===== SOURCE AGENT =====
let session = client
    .start_session_with_metadata(agent, json!({"user_id": "user-u_9k3m", "channel": "webchat"}))
    .await?;

client.store_memory(
    StoreMemoryRequest::new(agent, "User reports $89.99 unauthorized charge TXN-88291 on Jan 15.")
        .with_importance(0.85)
        .with_tags(vec!["billing".into(), "dispute".into()])
        .with_session(session.id.clone()),
).await?;

// Handoff summary at importance 1.0, then end the session with a short summary
client.store_memory(
    StoreMemoryRequest::new(agent, concat!(
        "HANDOFF SUMMARY [HIGH]: User Maria Santos disputes $89.99 TXN-88291 Jan 15. ",
        "Standard refund failed (30d limit). Credit rejected. Third contact. ",
        "Sentiment: high frustration. Action: supervisor override refund required.",
    ))
    .with_importance(1.0)
    .with_tags(vec!["handoff".into(), "session-summary".into(), "priority:high".into()])
    .with_session(session.id.clone()),
).await?;
client.end_session(&session.id, Some("Escalated to a human agent".to_string())).await?;

// ===== TARGET AGENT =====
client
    .start_session_with_metadata(agent, json!({"handler": "human-sarah", "handoff_from": session.id}))
    .await?;

// Importance 1.0 ranks the summary high; to filter by tag and session, use the
// REST body (tags, session_id) as in the REST tab. Here: pick it out by its prefix.
let found = client.recall(
    RecallRequest::new(agent, "billing dispute refund situation and resolution attempts").with_top_k(8),
).await?;
if let Some(summary) = found.memories.iter().find(|m| m.content.starts_with("HANDOFF SUMMARY")) {
    println!("Handoff summary: {}", summary.content);
}

ctx := context.Background()
client := dakera.NewClientWithOptions(dakera.ClientOptions{
    BaseURL: "http://localhost:3000",
    APIKey:  os.Getenv("DAKERA_API_KEY"),
})
agent := "support-bot"

// ===== SOURCE AGENT =====
session, _ := client.StartSession(ctx, dakera.StartSessionRequest{
    AgentID:  agent,
    Metadata: map[string]interface{}{"user_id": "user-u_9k3m", "channel": "webchat"},
})

eventImp, summaryImp := float32(0.85), float32(1.0)
client.StoreMemory(ctx, agent, dakera.StoreMemoryRequest{
    Content:    "User Maria Santos disputes $89.99 charge TXN-88291 from Jan 15. Not authorized.",
    Importance: &eventImp,
    Tags:       []string{"billing", "dispute"},
    SessionID:  session.ID,
})

// Handoff summary at importance 1.0, then end the session
client.StoreMemory(ctx, agent, dakera.StoreMemoryRequest{
    Content: "HANDOFF SUMMARY [HIGH]: User: Maria Santos. Goal: refund $89.99 TXN-88291 Jan 15. " +
        "Tried: standard refund (30d limit failed), credit ($90 rejected). 3rd contact. High frustration. " +
        "Action: supervisor override required. Bot committed 5-min ETA.",
    Importance: &summaryImp,
    Tags:       []string{"handoff", "session-summary", "priority:high"},
    SessionID:  session.ID,
})
client.EndSession(ctx, session.ID) // EndSession sends no summary in dakera-go

// ===== TARGET AGENT =====
client.StartSession(ctx, dakera.StartSessionRequest{
    AgentID:  agent,
    Metadata: map[string]interface{}{"handler": "human-sarah", "handoff_from": session.ID},
})

// Importance 1.0 ranks the summary high; to filter by tag and session, use the
// REST body (tags, session_id) as in the REST tab. Here: pick it out by its prefix.
found, _ := client.Recall(ctx, agent, dakera.RecallRequest{
    Query: "billing dispute refund situation attempts",
    TopK:  8,
})
for _, m := range found.Memories {
    if strings.HasPrefix(m.Content, "HANDOFF SUMMARY") {
        fmt.Printf("Handoff summary: %s\n", m.Content)
        break
    }
}