Emend
Build

Configuration Guide

Complete reference for all Emend configuration options including profile extraction, playbook, and evaluation settings.

This guide explains all configuration options available in Emend. Configuration controls how profiles are extracted, playbooks are generated, and agent performance is evaluated.

Overview

Emend uses a centralized Config object that contains settings for:

Storage Configuration

SQLite, Supabase, or PostgreSQL.

LLM Configuration

Provider API keys and model selection.

Extractors & Evaluation

Profile extraction, playbook aggregation, and success evaluation.

Getting and Setting Configuration

Configure Emend programmatically using the client when you want to override defaults. There are two ways to write config, depending on what you're changing:

  • update_config — a partial (PATCH-style) update of one or more top-level fields. The server merges your changes into the existing config atomically, so you only send the fields you're changing. This is the recommended way to override a single default.
  • get_config → set_config — fetch the full config, modify it, and send it back. Use this when you need to replace a nested object (e.g. an extractor config) wholesale.
Hosted Enterprise
If you're using Emend Enterprise, you can also configure settings visually via the web portal under the Settings page.

Partial update (recommended)

Send only the top-level fields you want to change:

from emend import EmendClient client = EmendClient()  # uses EMEND_API_KEY env var# Self-hosted: client = EmendClient(url_endpoint="http://localhost:8081") # Override one or more top-level fields — no need to re-send the full configclient.update_config({"window_size": 20, "stride_size": 10})
Warning
update_config does a top-level shallow merge — nested objects (e.g. profile_extractor_config, storage_config) are replaced wholesale, not deep-merged. To change a single field inside a nested object, use the full-config round-trip below.

Full / nested edits

Fetch the config, modify a nested object, and send the whole thing back:

from emend import EmendClient client = EmendClient()  # uses EMEND_API_KEY env var# Self-hosted: client = EmendClient(url_endpoint="http://localhost:8081") # Get current configurationconfig = client.get_config() # Modify a nested config objectconfig.profile_extractor_config = ... # Save the full configurationclient.set_config(config)

General Settings

Agent Context

Optionally provide global context about the agent's environment that should be shared across all extractors and evaluations.

config.agent_context_prompt = """This agent is a customer service representative for an e-commerce platform.The agent helps customers with:- Product inquiries and recommendations- Order tracking and status updates- Returns and refunds- Technical support for the website"""

Extraction Window Configuration

Emend uses a sliding window to group interactions for extraction. This controls how many interactions are processed together and how frequently extraction runs.

config.window_size = 10  # Number of interactions per extractionconfig.stride_size = 5  # New interactions before next extraction
PropTypeDescription
window_sizeintNumber of interactions included in each extraction window.
stride_sizeintNumber of new interactions that trigger the next extraction.
skip_should_run_checkboolSkip the LLM pre-extraction eligibility check — extraction always runs. Default: False.

Example: With window_size=10 and stride_size=5:

  • First extraction processes interactions 1-10
  • After 5 new interactions arrive, next extraction processes interactions 6-15
  • After 5 more, next extraction processes interactions 11-20

This overlapping window ensures context continuity between extractions while avoiding redundant processing of every single interaction.

Complete Configuration Example

from emend import EmendClientfrom emend.models.config_schema import (    Config,    ProfileExtractorConfig,    UserPlaybookExtractorConfig,    PlaybookAggregatorConfig,    AgentSuccessConfig,    ToolUseConfig) client = EmendClient()  # see Quickstart for connection options # Get current config (storage defaults to SQLite — no configuration needed)config = client.get_config() # Configure agent contextconfig.agent_context_prompt = """Customer service agent for an online booking platform.Helps users book hotels, flights, and activities.""" # Optional: customize profile extractionconfig.profile_extractor_config = ProfileExtractorConfig(    extraction_definition_prompt="""    Extract: name, travel preferences, budget range,    frequent destinations, loyalty program status    """,    context_prompt="Travel booking conversation",    tagging_definition_prompt="category: 'traveler_profile'") # Optional: customize playbook collectionconfig.user_playbook_extractor_config = UserPlaybookExtractorConfig(    extraction_definition_prompt="""    Was the booking process smooth? Any pain points?    Did the agent provide helpful recommendations?    """,    aggregation_config=PlaybookAggregatorConfig(        min_cluster_size=10,        reaggregation_trigger_count=5    )) # Configure tools the agent can use (shared across evaluation and extraction)config.tool_can_use = [    ToolUseConfig(        tool_name="search_availability",        tool_description="Search available options"    ),    ToolUseConfig(        tool_name="create_reservation",        tool_description="Create a new reservation"    )] # Configure success evaluation (enabled by default at 5% sampling)config.agent_success_config = AgentSuccessConfig(    success_definition_prompt="""    Success: Customer completed a booking or has clear next steps.    Failure: Customer left confused, frustrated, or without resolution.    """,    sampling_rate=1.0) # Configure extraction windowsconfig.window_size = 20config.stride_size = 10 # Save configurationclient.set_config(config)

Best Practices

  • Start with the defaults - Publish real interactions before tuning profile_extractor_config or user_playbook_extractor_config
  • Customize prompts after review - Once you see real extracted profiles and playbooks, make prompt overrides specific. Vague prompts lead to inconsistent results
  • Review evaluation samples - Agent success evaluation is enabled by default with sampling_rate=0.05. Increase it for launches or audits, and lower it if you need tighter cost control
  • Monitor playbook thresholds - Set min_cluster_size high enough to get meaningful aggregations
  • Filter by source - Use request_sources_enabled to process only relevant interaction types
  • Iterate on definitions - Review extracted profiles and adjust prompts based on results

Next Steps

PreviousConnection & AuthenticationNext Extractors & Evaluation