Emend
Getting Started

Hosted Enterprise Get Started

Connect to Hosted Enterprise, publish an interaction, and retrieve learned context.

This path connects your agent to Emend at https://www.emend.online.

Let your coding agent handle the integration
Give Codex, Claude Code, or Cursor this prompt while it is working in your agent application’s repository:
Follow the Emend quickstart to integrate Emend into my agent:https://www.emend.online/docs/getting-started/quickstartImplement the publish/search loop described there, end to end.

Before You Start

You need:

  • An Emend Enterprise account (open registration — no invitation required)
  • An API key from the portal
  • An LLM provider key configured in Emend or ready to add from Settings

New accounts use managed Emend storage by default. Start with Account Setup if you still need to create an account, verify your email, or generate a first API key.

1. Install the Client

pip install emend-clientuv add emend-client

The lightweight emend-client package is recommended for Hosted Enterprise integrations. It uses the same emend import as Local OSS:

from emend import EmendClient

2. Connect

Use the Python SDK in application code. Use cURL when checking an API key, debugging auth, or confirming raw endpoint behavior.

export EMEND_API_KEY="your-api-key"from emend import EmendClient client = EmendClient()identity = client.whoami() print(identity.org_id, identity.storage_type, identity.storage_label)

Store new API keys securely. Emend shows the full key only once and displays only its prefix afterward.

3. Publish an Interaction

Publish the full turn after your agent responds, including user feedback. Durable facts become profiles; corrective feedback becomes user playbooks. Emend stores the interaction immediately and runs extraction asynchronously.

Info
This first conversation seeds learning, so it has no retrieved_learnings. Once you retrieve and inject context, we recommend reporting every injected learning on the assistant turn. Step 6 shows this using actual search-result IDs so you can measure relevance and impact without guessing which learning helped.

Detailed API spec: publish_interaction.

from emend import EmendClient, InteractionData, UserActionType client = EmendClient() client.publish_interaction(    user_id="user_123",    interactions=[        InteractionData(            role="User",            content="I'm a backend software engineer and I travel for work most weeks. Can you recommend a laptop under $1,500?",            user_action=UserActionType.NONE,        ),        InteractionData(            role="Agent",            content="Sure — here's a powerful gaming laptop with 32 GB RAM, just under $1,500.",            user_action=UserActionType.NONE,        ),        InteractionData(            role="User",            content="That's far too bulky for constant travel — next time skip the gaming laptops and prioritize battery life and weight.",            user_action=UserActionType.NONE,        ),    ],    source="support-agent:v2",    session_id="session_001",)

What this interaction teaches Emend

  • Profile (durable memory): “Backend software engineer who travels for work most weeks.”
  • User playbook (behavioral steering): “When recommending a laptop for software development, avoid bulky gaming models — prioritize battery life and weight.”

4. Trigger Extraction for This Example

Emend extracts automatically once a user accumulates a full sliding window of interactions — by default window_size is 10. This quickstart published only a few, so automatic extraction has not fired yet. To see results right away, trigger extraction manually for this demo.

Demo only — don't do this in production
You normally never call these. In production you just keep publishing interactions, and Emend extracts on its own once each user reaches the window. The manual triggers below exist only so this short walkthrough produces a profile and a playbook immediately — don’t wire them into your publish path.

Detailed API spec: manual_profile_generation, manual_playbook_generation.

from emend import EmendClient client = EmendClient() # Force extraction now so this short demo produces results immediately.client.manual_profile_generation(user_id="user_123")client.manual_playbook_generation()  # uses the same default agent version as publish # Extraction runs asynchronously — give it a few seconds before searching.

5. Retrieve Context Before the Next Response

Retrieve both the user’s profiles (durable memory) and the playbooks (behavioral steering learned from feedback) before the next response. One unified search returns the profile and playbook you just extracted, alongside any team-wide agent playbooks.

Detailed API spec: search.

from emend import EmendClient client = EmendClient()user_id = "user_123" context = client.search(    query="laptop preferences and how to advise this user",    user_id=user_id,    top_k=5,    entity_types=["profiles", "user_playbooks", "agent_playbooks"],) profile_context = "\n".join(f"- {p.content}" for p in context.profiles)user_playbook_context = "\n".join(f"- {pb.content}" for pb in context.user_playbooks)agent_playbook_context = "\n".join(f"- {pb.content}" for pb in context.agent_playbooks) prompt = f"""Use this Emend context when responding. What we know about this user (profiles):{profile_context or "- No profiles yet."} How this user has steered the agent (user playbooks):{user_playbook_context or "- No playbooks yet."} Team-wide agent playbooks:{agent_playbook_context or "- No playbooks yet."}"""

6. Publish the Context-Aware Response and Check Quality

Continue with the context and prompt above. This example injects all returned learnings; if you filter or truncate them, build the prompt and references from the same retained subset. call_your_llm represents your application’s model call.

retrieved_learnings = [    *({"kind": "profile", "learning_id": p.profile_id} for p in context.profiles),    *({"kind": "user_playbook", "learning_id": str(p.user_playbook_id)}      for p in context.user_playbooks),    *({"kind": "agent_playbook", "learning_id": str(p.agent_playbook_id)}      for p in context.agent_playbooks),]user_message = "What should I prioritize when choosing my next laptop?"answer = call_your_llm([    {"role": "system", "content": prompt},    {"role": "user", "content": user_message},])client.publish_interaction(    user_id=user_id,    session_id="session_002",    agent_version="support-agent@2",    interactions=[        InteractionData(role="User", content=user_message),        InteractionData(role="Agent", content=answer,                        retrieved_learnings=retrieved_learnings),    ],    retrieval_experiment_id=(context.experiment.experiment_id if context.experiment else None),    retrieval_experiment_arm=(context.experiment.arm if context.experiment else None),    wait_for_response=True,) # Grade after the session is complete; this runs LLM judges and may incur cost.grade = client.grade_on_demand(session_id="session_002", agent_version="support-agent@2")print("Retrieved-learning evaluation:", grade.retrieved_learning_status)print("Skipped:", grade.skipped_reason, "Cached:", grade.cached)verdicts = client.get_retrieved_learning_evaluation_results(    user_id=user_id, session_id="session_002", limit=100,)for verdict in verdicts.results:    print(verdict.interaction_id, verdict.kind, verdict.learning_id)    print("Relevant:", verdict.is_relevant, verdict.relevance_reason)    print("Impact:", verdict.impact, verdict.impact_reason)

Relevance asks whether a learning applied; impact asks whether it helped, harmed, or made no material difference. A null verdict is ungraded, not irrelevant or neutral. Empty results are not proof that retrieval failed: check the grade status, attached IDs, and whether any context was injected.

For automatic monitoring, configure the success rubric and retrieved_learning_sampling_rate; publishing does not immediately produce verdicts. See evaluation setup and troubleshooting.

7. Inspect the Loop

Use the portal to confirm data is flowing:

  • Interactions shows published conversations and metadata.
  • Profiles shows extracted user memory.
  • Playbooks shows user playbooks and aggregated agent playbooks.
  • Evaluation shows success rates, retrieved-learning relevance and impact, coverage counts, and per-learning judge reasons. See the metric definitions.

Next Steps

Next Local OSS Get Started