exemplar-harness-sdk

Python SDK for Exemplar: session ingest, long-term memory, skills, and prompts.

Quick start covers Agno, OpenAI SDK, Google ADK, and Claude Agent SDK. More frameworks — see Framework extras.

Related package: terminal CLI — exemplar-cli (docs, examples).

Contents

• Install
• Quick start
  • Agno
  • OpenAI SDK
  • Google ADK
  • Claude Agent SDK
• Session ingest
  • Example 1 — Framework helper (Agno)
  • Example 2 — Direct ingest (no framework)
• Memory
  • Example 1 — Add and recall
  • Example 2 — Search and update
• Skills
  • Example 1 — Create and list
  • Example 2 — Get and search
• Prompts
  • Example 1 — Create and run
  • Example 2 — Build for your own agent framework
  • Example 3 — List and get
• CLI (separate package)
• Advanced usage
  • Session ingest — Session helper with auto judge
  • Memory — Generic hook in any agent loop
  • Skills — Export Cursor-compatible SKILL.md
  • Prompts — Publish, build for frameworks, or run inline
• Framework extras
• Reference
  • Optional install extras
  • Envelope v1

Install

pip install exemplar-harness-sdk

# One agent framework (pick what you use)
pip install "exemplar-harness-sdk[agno]"
pip install "exemplar-harness-sdk[openai]"
pip install "exemplar-harness-sdk[google-adk]"
pip install "exemplar-harness-sdk[claude-agent]"

# Everything
pip install "exemplar-harness-sdk[all]"

export EXEMPLAR_API_KEY="eis_your_org_api_key"

Licensed for non-commercial use only. Commercial use requires a separate license from Exemplar Dev LLC. See LICENSE.

Quick start

Pick your agent framework. Reuse the same session_id for every turn in a conversation — integrations call Harness.ingest() for you (Google ADK: call ingest_adk_session after the run).

flowchart LR
  Agent[Your agent] --> Integration[SDK integration]
  Integration --> Harness[Harness.ingest]
  Harness --> API[Exemplar platform API]
  API --> Eval[Harness eval]

Agno

pip install "exemplar-harness-sdk[agno]"

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from exemplar_harness import Harness
from exemplar_harness.integrations.agno import harness_agno_post_hook

harness = Harness.from_env()
agent = Agent(
    name="support-bot",
    model=OpenAIChat(id="gpt-4o"),
    post_hooks=[
        harness_agno_post_hook(
            harness,
            session_id="sess-abc",
            agent_name="support-bot",
            source_app="my-app",
        )
    ],
)
agent.run("Summarize our refund policy.")

OpenAI SDK

pip install "exemplar-harness-sdk[openai]"

from openai import OpenAI
from exemplar_harness import Harness
from exemplar_harness.integrations.openai import HarnessOpenAICallback, sdk_chat_completion

harness = Harness.from_env()
callback = HarnessOpenAICallback(
    harness,
    session_id="sess-abc",
    agent_name="support-bot",
    source_app="my-app",
)
client = OpenAI()
sdk_chat_completion(
    harness,
    callback,
    client,
    model="gpt-4o",
    messages=[{"role": "user", "content": "Summarize our refund policy."}],
)

Google ADK

pip install "exemplar-harness-sdk[google-adk]"

import asyncio

from exemplar_harness import Harness
from exemplar_harness.integrations.google_adk import ingest_adk_session
from google.adk.agents import LlmAgent
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.genai import types

harness = Harness.from_env()
session_id, app_name, user_id = "sess-abc", "my_app", "user-1"

agent = LlmAgent(
    model="gemini-2.5-flash",
    name="support_bot",  # must be a valid Python identifier
    instruction="Answer concisely.",
)
sessions = InMemorySessionService()


async def run_and_ingest() -> None:
    await sessions.create_session(app_name=app_name, user_id=user_id, session_id=session_id)
    runner = Runner(agent=agent, app_name=app_name, session_service=sessions)
    message = types.Content(role="user", parts=[types.Part(text="Summarize our refund policy.")])
    async for _ in runner.run_async(user_id=user_id, session_id=session_id, new_message=message):
        pass
    session = await sessions.get_session(app_name=app_name, user_id=user_id, session_id=session_id)
    ingest_adk_session(
        harness,
        session.model_dump(mode="json", exclude_none=True),
        session_id=session_id,
        agent_name="support-bot",
        source_app="my-app",
    )


asyncio.run(run_and_ingest())

Claude Agent SDK

pip install "exemplar-harness-sdk[claude-agent]"

import asyncio

from exemplar_harness import Harness
from exemplar_harness.integrations.claude_agent import HarnessClaudeAgentHandler

harness = Harness.from_env()
handler = HarnessClaudeAgentHandler(
    harness,
    session_id="sess-abc",
    agent_name="support-bot",
    source_app="my-app",
)
asyncio.run(handler.run_query("Summarize our refund policy."))

Session ingest

Base helper: Harness.ingest() / framework helpers above.

Example 1 — Framework helper (Agno)

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from exemplar_harness import Harness
from exemplar_harness.integrations.agno import harness_agno_post_hook

harness = Harness.from_env()
agent = Agent(
    name="support-bot",
    model=OpenAIChat(id="gpt-4o"),
    post_hooks=[harness_agno_post_hook(harness, session_id="sess-abc", agent_name="support-bot")],
)
agent.run("What is the return window?")

Example 2 — Direct ingest (no framework)

from exemplar_harness import Harness

harness = Harness.from_env()
harness.ingest(
    "generic",
    session_id="sess-abc",
    event="turns",
    data={
        "turns": [
            {
                "input": "What is harness eval?",
                "output": "Automated judge over agent sessions.",
                "model": "gpt-4o",
            }
        ]
    },
    agent_name="my-agent",
    source_app="my-app",
)

Memory

Base helper: harness.memory(...).

Example 1 — Add and recall

from exemplar_harness import Harness

harness = Harness.from_env()
memory = harness.memory(user_id="user-123", session_id="chat-abc", app_id="my-app")

memory.add("User prefers bullet-point answers.", memory_type="preference")
context = memory.recall("how should I format answers?")  # inject into system prompt

Example 2 — Search and update

results = memory.search("formatting preferences", top_k=5)
listed = memory.list(limit=20)
record = memory.get(listed[0].memory_id)
memory.update(record.memory_id, content="User prefers numbered lists.")
memory.delete(record.memory_id)

Skills

Base helper: harness.skills().

Example 1 — Create and list

from exemplar_harness import Harness

harness = Harness.from_env()
skills = harness.skills()

record = skills.create(
    name="refund-policy",
    instructions="# Refund policy\n\nReturns within 30 days.",
    description="Refund workflow",
    tags=["support"],
)
items = skills.list(limit=20)

Example 2 — Get and search

fetched = skills.get("refund-policy")  # by ID or unique name
hits = skills.search("refund", top_k=5)

Prompts

Base helper: harness.prompts().

Example 1 — Create and run

from exemplar_harness import Harness

harness = Harness.from_env()
prompts = harness.prompts()

record = prompts.create(
    name="support-summary",
    title="Support summary",
    messages=[
        {"role": "system", "content": "Be concise."},
        {"role": "user", "content": "Summarize topic: {{topic}}."},
    ],
    variables=["topic"],
)
result = prompts.run("support-summary", variables={"topic": "returns"})
print(result["content"])

Example 2 — Build for your own agent framework

Fetch a stored prompt, substitute {{variables}} locally, and hand messages to LangGraph, OpenAI, Haystack, etc. Does not call Exemplar’s model runner.

built = prompts.build("support-summary", variables={"topic": "returns"})
# built.messages -> [{"role": "system", ...}, {"role": "user", ...}]
# built.model    -> default model from the registry (if set)
# pass built.messages into your framework / LLM client

Or reuse an already-fetched record (no second network call):

record = prompts.get("support-summary")
built = record.build(variables={"topic": "returns"})

Example 3 — List and get

listed = prompts.list(limit=20)
fetched = prompts.get("support-summary")  # by ID or unique name
hits = prompts.search("support", top_k=5)

CLI (separate package)

Skills, prompts, and memory are also available as a standalone terminal package — not bundled with this SDK:

pip install exemplar-cli
export EXEMPLAR_API_KEY="eis_your_org_api_key"
exemplar doctor

Advanced usage

One advanced pattern per offering. For full framework wiring, see examples/live/.

Session ingest — Session helper with auto judge

from exemplar_harness import Harness

harness = Harness.from_env()
session = harness.session(
    "sess-abc",
    agent_name="support-bot",
    source_app="my-app",
    auto_judge_run=True,  # run judge after each ingest through this session
)
session.ingest(
    "generic",
    event="turns",
    data={"turns": [{"input": "Hello", "output": "Hi!", "model": "gpt-4o"}]},
)

Memory — Generic hook in any agent loop

from exemplar_harness import Harness
from exemplar_harness.integrations.memory import MemoryHook

harness = Harness.from_env()
memory = harness.memory(user_id="user-123", session_id="chat-abc", app_id="my-app")
hook = MemoryHook(memory, recall_top_k=5, auto_add=False)

user_input = "What do you know about me?"
recall = hook.before_turn(user_input)  # prepend to system prompt
# ... run LLM ...
hook.after_turn(user_input, assistant_output)  # no-op unless auto_add=True

Skills — Export Cursor-compatible SKILL.md

from pathlib import Path

from exemplar_harness import Harness

skills = Harness.from_env().skills()
skill_md = skills.export_skill_md("refund-policy")
Path(".cursor/skills/refund-policy/SKILL.md").write_text(skill_md)

Prompts — Publish, build for frameworks, or run inline

from exemplar_harness import Harness

prompts = Harness.from_env().prompts()

prompts.publish_version(
    "support-summary",
    messages=[
        {"role": "system", "content": "Be concise."},
        {"role": "user", "content": "Bullet summary for: {{topic}}."},
    ],
    change_notes="Use bullets",
)

# Hand off to your agent framework (local {{var}} substitution)
built = prompts.build("support-summary", variables={"topic": "returns"})

# Or execute via Exemplar without a stored prompt
inline = prompts.run_inline(
    messages=[
        {"role": "system", "content": "Be concise."},
        {"role": "user", "content": "Say hello."},
    ],
    model="openai/gpt-4o-mini",
)

Framework extras

Matching memory helpers live under exemplar_harness.integrations.memory.*.

# List / run live demos
python -m examples.live.run_all --list
python -m examples.live.run_platform_demos --list
HARNESS_EXAMPLES_SIMULATED=1 python -m examples.live.run_platform_demos

Reference

Optional install extras

Vercel AI SDK is not included in the Python package (TypeScript SDK path).

Envelope v1

Each ingest POSTs schemaVersion: 1 to POST /api/harness-ingest/v1/sessions with a sourceType and framework-native data payload. The Exemplar platform API maps envelopes to eval session turns. Harness judge runs use POST /api/harness-judge/v1/runs; per-turn session eval uses POST /api/harness-session-eval/v1/sessions/{sessionId}.