Collecting and Using Playbooks

Emend ships with a default playbook extractor. Published corrections and successful procedures become user playbooks; recurring patterns can aggregate into agent playbooks for human approval.

Collect Useful Evidence

Publish the complete turn, including the user's correction or confirmation, and set agent_version consistently.

client.publish_interaction(    user_id="customer_123",    session_id="billing_001",    source="support-agent:v2",    agent_version="support-agent@2.4.0",    interactions=[        {"role": "User", "content": "Please update my billing email."},        {"role": "Agent", "content": "Done—the email is now changed."},        {            "role": "User",            "content": "You must verify account ownership before changing billing details.",        },    ],)

Use expert_content when an expert has supplied the preferred response. Do not manufacture positive feedback merely to trigger extraction.

Retrieve Guidance

Unified search is the recommended serving path:

context = client.search(    query="user wants to change sensitive account details",    user_id="customer_123",    agent_version="support-agent@2.4.0",    entity_types=["user_playbooks", "agent_playbooks"],    agent_playbook_status_filter=["approved"],    top_k=5,)

When an agent playbook represents a returned source user playbook, Emend suppresses the duplicate user playbook. Result arrays may therefore contain fewer than top_k items.

Inspect User Playbooks

Use get_user_playbooks to inspect source-level guidance or filter by user, request, playbook name, agent version, status, time, or tag. Use search_user_playbooks when semantic relevance matters.

evidence = client.get_user_playbooks(    user_id="customer_123",    agent_version="support-agent@2.4.0",    status_filter=[None],)

Aggregate and Review Agent Playbooks

Aggregation normally runs according to configuration. Operators can also trigger it explicitly for an agent version:

client.run_playbook_aggregation(    agent_version="support-agent@2.4.0",    wait_for_response=True,)

Review pending results in the Hosted Enterprise portal or with get_agent_playbooks, then update status to approved or rejected.

Customize Carefully

Tune the playbook definition only after reviewing actual extracted evidence. Keep it behavioral and actionable; user facts belong in profiles.

client.update_config({    "user_playbook_extractor_config": {        "extraction_definition_prompt": (            "Extract reusable procedures and explicit corrections about handling sensitive account changes."        ),        "aggregation_config": {            "min_cluster_size": 3,            "reaggregation_trigger_count": 2,        },    }})

Nested objects are replaced rather than deep-merged, so preserve any existing nested fields you still need.

For the two-scope lifecycle, see Playbooks. For every management method and schema, see the Playbook API Reference.