Sessions in Julep enable persistent, stateful interactions between users and agents. They maintain context across multiple exchanges and can be used to build conversational interfaces.
Creating Sessions
// Create a new session
const session = await client.sessions.create({
agent_id: agentId,
user_id: userId, // Optional
metadata: {
channel: 'web',
language: 'english'
},
context_overflow: 'adaptive' // or 'truncate' or 'summarize'
});
Session Chat
// Send a message and get a response
const response = await client.sessions.chat(sessionId, {
messages: [
{
role: 'user',
content: 'Hello! Can you help me with my order?'
}
]
});
// Continue the conversation in the same session
const followUp = await client.sessions.chat(sessionId, {
messages: [
{
role: 'user',
content: 'I need to change my shipping address.'
}
]
});
Managing Context
Sessions automatically maintain context, but you can also manage it manually:
// Add context to the session
await client.sessions.update(sessionId, {
metadata: {
order_id: '12345',
customer_tier: 'premium'
}
});
// Get session history
const history = await client.sessions.history(sessionId, {
limit: 10,
offset: 0
});
Tools can be added specifically for a session:
// Add a session-specific tool
await client.sessions.tools.create(sessionId, {
name: 'check_order_status',
description: 'Check the status of an order',
type: 'function',
function: {
parameters: {
type: 'object',
properties: {
order_id: {
type: 'string',
description: 'The order ID to check'
}
},
required: ['order_id']
}
}
});
Session Documents
Add relevant documents to the session for context:
// Add a document to the session
const document = await client.sessions.docs.create(sessionId, {
title: 'Order Details',
content: 'Order #12345: 2 items, shipping to...',
metadata: {
order_id: '12345',
type: 'order_details'
}
});
// Search session documents
const docs = await client.sessions.docs.search(sessionId, {
query: 'shipping policy',
metadata: {
type: 'policy'
}
});
Managing Sessions
// Get a specific session
const session = await client.sessions.get(sessionId);
// List all sessions
const sessions = await client.sessions.list({
limit: 10,
offset: 0,
agent_id: agentId // Optional filter
});
// Update a session
const updatedSession = await client.sessions.update(sessionId, {
metadata: {
status: 'resolved'
}
});
// Delete a session
await client.sessions.delete(sessionId);
Error Handling
try {
const response = await client.sessions.chat(sessionId, {
messages: [
{
role: 'user',
content: 'Hello!'
}
]
});
} catch (error) {
if (error.name === 'SessionError') {
console.error('Session error:', error.message);
} else if (error.name === 'ApiError') {
console.error('API error:', error.message, error.status);
} else {
console.error('Unexpected error:', error);
}
}
Context Overflow Strategies
Julep provides different strategies for handling context overflow:
// Adaptive strategy (default)
const adaptiveSession = await client.sessions.create({
agent_id: agentId,
context_overflow: 'adaptive'
});
// Truncate strategy
const truncateSession = await client.sessions.create({
agent_id: agentId,
context_overflow: 'truncate'
});
// Summarize strategy
const summarizeSession = await client.sessions.create({
agent_id: agentId,
context_overflow: 'summarize'
});
Next Steps
