Client usage

from exemplar_harness import Harness
 
harness = Harness.from_env()

import { Harness } from "@exemplar-dev/exemplar-harness-typescript-sdk";
 
const harness = Harness.fromEnv({ agentId: "support-bot" });

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")
 
# Prompt-ready string (server-rendered body when available)
context = memory.recall(
    "how should I format answers?",
    format="markdown",
    search_mode="hybrid",
)
 
# Structured hits
results = memory.search(
    "formatting preferences",
    top_k=5,
    search_mode="hybrid",
    format="json",
)
 
# Records + rendered body (toon / markdown / json_compact)
envelope = memory.search_envelope("theme settings", format="toon", search_mode="hybrid")
prompt_block = envelope.body  # inject into the system prompt
 
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)

from exemplar_harness.integrations.memory import MemoryHook
 
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

const memory = harness.memory({
  userId: "user-123",
  sessionId: "chat-abc",
  appId: "my-app",
});
 
await memory.add("User prefers bullet-point answers.", { memoryType: "preference" });
 
const context = await memory.recall("how should I format answers?", {
  format: "markdown",
  searchMode: "hybrid",
});
 
const results = await memory.search("formatting preferences", {
  topK: 5,
  searchMode: "hybrid",
  format: "json",
});
 
const envelope = await memory.searchEnvelope("theme settings", {
  format: "toon",
  searchMode: "hybrid",
});
const promptBlock = envelope.body;
 
const listed = await memory.list({ limit: 20 });
const record = await memory.get(listed[0]!.memoryId);
await memory.update(record.memoryId, { content: "User prefers numbered lists." });
await memory.delete(record.memoryId);

skills = harness.skills()
 
record = skills.create(
    name="refund-policy",
    instructions="# Refund policy\n\nReturns within 30 days.\n\nSee [references/policy.md](references/policy.md).",
    description="Refund workflow",
    tags=["support"],
    files={"references/policy.md": "# Policy\n\n30-day returns.\n"},
)
items = skills.list(limit=20)
fetched = skills.get("refund-policy")
hits = skills.search("refund", top_k=5)
 
# Materialize SKILL.md + supporting files for agent runtimes
skills.install(".agents/skills", names=["refund-policy"])

const skills = harness.skills();
 
const record = await skills.create({
  name: "refund-policy",
  instructions:
    "# Refund policy\n\nReturns within 30 days.\n\nSee [references/policy.md](references/policy.md).",
  description: "Refund workflow",
  tags: ["support"],
  files: { "references/policy.md": "# Policy\n\n30-day returns.\n" },
});
const items = await skills.list({ limit: 20 });
const fetched = await skills.get("refund-policy");
const hits = await skills.search("refund", { topK: 5 });
 
await skills.install(".agents/skills", { names: ["refund-policy"] });

from exemplar_harness import Harness, HITLTimeoutError
 
harness = Harness.from_env(agent_id="deploy-agent")
hitl = harness.hitl()
 
try:
    result = hitl.ask(
        "Deploy build 1234 to production?",
        description="All checks green. Blast radius: payments service.",
        payload={"build": "1234", "service": "payments"},
        ttl_seconds=1800,   # server-side expiry
        timeout=1800,       # local wait budget (seconds)
        poll_interval=5,
    )
except HITLTimeoutError:
    result = None
 
if result and result.approved:
    deploy()
elif result and result.state == "rejected":
    print(f"Rejected: {result.response.comment}")

answer = hitl.ask("Which rollback strategy?", request_type="input")
print(answer.response.text)
 
choice = hitl.ask(
    "Pick a deployment region",
    request_type="select",
    options=["us-east-1", "eu-west-1"],
)
print(choice.response.option)
 
request = hitl.request_approval("Rotate production credentials?")
status = hitl.get(request.request_id)
if status.is_pending:
    hitl.cancel(request.request_id)

from langchain_core.tools import tool
 
@tool
def ask_human_approval(question: str) -> str:
    """Ask a human operator to approve or reject an action."""
    result = harness.hitl().ask(question, timeout=900)
    if result.approved:
        return "approved"
    return f"denied ({result.state}): {result.response.comment or 'no comment'}"

import {
  Harness,
  HITLTimeoutError,
} from "@exemplar-dev/exemplar-harness-typescript-sdk";
 
const harness = Harness.fromEnv({ agentId: "deploy-agent" });
const hitl = harness.hitl();
 
let result;
try {
  result = await hitl.ask("Deploy build 1234 to production?", {
    description: "All checks green. Blast radius: payments service.",
    payload: { build: "1234", service: "payments" },
    ttlSeconds: 1800,
    timeout: 1800,
    pollInterval: 5,
  });
} catch (err) {
  if (err instanceof HITLTimeoutError) result = null;
  else throw err;
}
 
if (result?.approved) {
  // deploy…
} else if (result?.state === "rejected") {
  console.log(`Rejected: ${result.response.comment}`);
}
 
const answer = await hitl.ask("Which rollback strategy?", { requestType: "input" });
console.log(answer.response.text);
 
const choice = await hitl.ask("Pick a deployment region", {
  requestType: "select",
  options: ["us-east-1", "eu-west-1"],
});
console.log(choice.response.option);
 
const request = await hitl.requestApproval("Rotate production credentials?");
const status = await hitl.get(request.requestId);
if (status.isPending) await hitl.cancel(request.requestId);

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"])
 
# Local {{var}} substitution for your own agent framework (no Exemplar model call)
built = prompts.build("support-summary", variables={"topic": "returns"})
# built.messages -> [{"role": "system", ...}, {"role": "user", ...}]

prompts.publish_version(
    "support-summary",
    messages=[
        {"role": "system", "content": "Be concise."},
        {"role": "user", "content": "Bullet summary for: {{topic}}."},
    ],
    change_notes="Use bullets",
)
 
inline = prompts.run_inline(
    messages=[
        {"role": "system", "content": "Be concise."},
        {"role": "user", "content": "Say hello."},
    ],
    model="openai/gpt-4o-mini",
)

const prompts = harness.prompts();
 
const record = await prompts.create({
  name: "support-summary",
  title: "Support summary",
  messages: [
    { role: "system", content: "Be concise." },
    { role: "user", content: "Summarize topic: {{topic}}." },
  ],
  variables: ["topic"],
});
const result = await prompts.run("support-summary", {
  variables: { topic: "returns" },
});
console.log(result.content);
 
const built = await prompts.build("support-summary", {
  variables: { topic: "returns" },
});
// built.messages -> provider-ready messages
 
await prompts.publishVersion("support-summary", {
  messages: [
    { role: "system", content: "Be concise." },
    { role: "user", content: "Bullet summary for: {{topic}}." },
  ],
  changeNotes: "Use bullets",
});
 
await prompts.runInline({
  messages: [
    { role: "system", content: "Be concise." },
    { role: "user", content: "Say hello." },
  ],
  model: "openai/gpt-4o-mini",
});

from exemplar_harness import Harness
from exemplar_harness.relay import RelayDecision
 
harness = Harness.from_env(agent_id="support-bot")
relay = harness.relay(surface="langchain", source_app="my-app")
 
# LangChain / LangGraph create_agent middleware
agent = create_agent(
    model=...,
    tools=[...],
    middleware=[relay.langchain_middleware(session_id="sess-abc")],
)
 
# Pydantic AI
# agent = Agent(..., capabilities=[relay.pydantic_ai_hooks(session_id="sess-abc")])
 
# CrewAI: before, after = relay.crewai_hooks(session_id="sess-abc")
# Semantic Kernel: relay.semantic_kernel_register(kernel, session_id="sess-abc")
# Agno: tool_hooks=[relay.agno_tool_hook(session_id="sess-abc")]
 
# Hook-free dry-run (CI / preflight)
verdict = relay.evaluate(
    tool_name="shell",
    arguments={"command": "rm -rf /tmp/x"},
    user_id="user_123",
)
if verdict.decision is RelayDecision.DENY:
    raise RuntimeError(verdict.reason)

import { Harness } from "@exemplar-dev/exemplar-harness-typescript-sdk";
 
const harness = Harness.fromEnv({ agentId: "support-bot" });
const relay = harness.relay({
  surface: "mastra", // or openai_agents | claude_sdk | langchain | langgraph
  sourceApp: "my-app",
});
 
// Mastra
const mastraHooks = relay.mastraHooks("sess-abc");
// new Agent({ hooks: mastraHooks, ... })
 
// LangChain.js / LangGraph.js
const lcMw = relay.langchainMiddleware("sess-abc");
// createMiddleware(lcMw) → createAgent({ middleware: [...] })
 
// OpenAI Agents / Claude Agent SDK
const inputGuard = relay.openaiToolInput("sess-abc");
const hooks = relay.claudeHooks({ sessionId: "sess-abc" });
 
const [decision, reason] = await relay.verdict({
  sessionId: "sess-abc",
  toolName: "shell",
  arguments: { command: "ls" },
});
 
const verdict = await relay.evaluateBash({ command: "rm -rf /tmp" });
if (verdict.decision === "deny") {
  throw new Error(verdict.reason || "blocked by Relay");
}

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_id="my-agent",
    source_app="my-app",
)

await harness.ingest("generic", {
  sessionId: "sess-abc",
  event: "turns",
  data: {
    turns: [
      {
        input: "What is harness eval?",
        output: "Automated judge over agent sessions.",
        model: "gpt-4o",
      },
    ],
  },
  agentId: "my-agent",
  sourceApp: "my-app",
});

session = harness.session(
    "sess-abc",
    agent_id="support-bot",
    source_app="my-app",
    auto_judge_run=True,       # Insights (LLM judge)
    auto_session_eval=True,    # per-turn Session Evals
)
session.ingest(
    "generic",
    event="turns",
    data={"turns": [{"input": "Hello", "output": "Hi!", "model": "gpt-4o"}]},
)
 
# Or trigger judge later on existing sessions
harness.runs.trigger(session_ids=["sess-abc"], sync=False)

const session = harness.session("sess-abc", {
  agentId: "support-bot",
  sourceApp: "my-app",
  autoJudgeRun: true, // Insights (LLM judge)
  autoSessionEval: true, // per-turn Session Evals
});
await session.ingest("generic", {
  event: "turns",
  data: { turns: [{ input: "Hello", output: "Hi!", model: "gpt-4o" }] },
});
 
// Or trigger judge later on existing sessions
await harness.runs.trigger({ sessionIds: ["sess-abc"], sync: false });