LanguageEN繁
Home
Docs

Start here · Responsibility boundary

Reuse the runtime. Keep the product.

Heddle owns reusable agent mechanics. Your product remains the authority for users, data, policy, deployment, transport, and experience.

Customization depth

Applies at every customization level

Hosting depth

Applies at every hosting level

Documentation status

Canonical reference

Heddle owns
  • Messages, turns, continuation, compaction, leases, and persisted session behavior
  • Model/tool execution, approval lifecycle, traces, semantic activity, and artifacts
  • Optional run identity, ordered sequences, replay, cancellation, terminals, and remote envelope validation
Your product owns
  • Authenticated identity, tenant scope, access rules, and product relationships
  • Domain tools, system context, credentials, public schemas, retention, encryption, and backup
  • API framework, transport, routing, rate limits, deployment, UI state, and result application

Dependency direction

Text
YOUR PRODUCT
  UI state and result application
          |
  remote consumer + optional HTTP/SSE client
          |
  your transport, authentication, and public schemas
          |
  your application service and composition root
======================= HEDDLE SDK =======================
  ConversationRunService
  run identity, ordered activity, replay, cancel, approvals
          |
  ConversationEngine
  sessions, turns, compaction, traces, artifacts
          |
  models, tools, host extensions, MCP

Keep dependencies pointing downward. A transport-neutral application service should not read an HTTP request, and Heddle core should not know which frontend renders the result.

Complete responsibility split

ConcernHeddle ownsYour product owns
ConversationMessages, turns, continuation, compaction, leases, persisted behaviorStable product conversation ID, relationships, access rules
ExecutionModel/tool loop, registration, host extensions, traces, artifactsDomain tools, context, model choice, credentials, capability policy
ApprovalsRequest and resolution lifecycleWhether an action is allowed, authenticated approver, policy and UI
Active runsRun ID, ordered sequence, bounded replay, cancellation, terminal settlementAddress scope, process lifetime, routing, draining, distributed delivery
Remote clientEnvelope validation, cursor rules, duplicate/gap handling, terminal detectionPublic fields, timers, UI state, retry UX, notifications, result presentation
PersistenceLocal defaults and injectable session/artifact portsProduction adapters, tenant binding, retention, encryption, backup
API and UIOptional transport mechanicsFramework, routes, authorization, CORS, limits, errors, every visual decision

Avoid duplicate runtime behavior

Do not add a second implementation of mechanics Heddle already owns:

  • Do not replay the product's complete chat history into every new prompt. Reuse the same Heddle session ID.
  • Do not create a second host-side run ID for the same active Heddle run.
  • Do not add another in-process event bus above ConversationRunService.
  • Do not treat one subscriber disconnect as cancellation of the underlying run.
  • Do not parse rendered assistant text to recover structured failures or tool results.
  • Do not expose internal traces, tool inputs, paths, or provider errors without an explicit public projection.

Before implementation

Write down these host decisions:

  1. Which server framework and transport already exist?
  2. How are identity and tenant scope authenticated?
  3. Which stable product ID maps to a Heddle conversation?
  4. Which UI/state layer consumes run events?
  5. Can one process own an active run for its lifetime?
  6. Which repositories, approval policy, tools, and telemetry are production requirements?

Then select the lowest matching layer and copy only the example stages whose assumptions match.

Continue to Build your first agent, or go directly to Hosting overview when your product already owns its conversation UI.

Canonical sources