Runtime API
Manual capture never changes application exceptions or cancellation identity. Serialization loss leaves an
explicit partial or omission marker. Stream output records consumed chunks in a JSON array. A capturable
non-
None sync generator return uses a single output.value JSON object containing chunks and return,
identified by impact.capture.output.format="stream-chunks-and-return". The output follows the boundary’s
content controls. Context identifiers allow 1,024 UTF-8 bytes and purpose allows 65,536. Empty strings, NUL,
malformed Unicode and unknown fields reject before capture.
Record a logical request
Initialize Impact to observe ordinary provider calls in the integration catalogue. Wrap an application request withinteraction() to connect its native model, tool and service calls to its
outcome. Use the configuration and dependencies from the quickstart to run this
example. It makes one billable provider call.
interaction() preserves the callback’s native value or awaitable and invokes it once. Omit interaction_id
to create one UUID at that explicit request boundary. Several requests can share an optional Session. A User
ID is an opaque application key, not an authenticated person. Plain context, span and operation scopes
never create an Interaction or independently finish their parent request. Set stable deployment defaults with
init(context=impact.ImpactContext(...)) using environment, version_id, component_id, build_id and
deployment_id when those values are known. environment is a reported environment name. version_id is a
reported deployed-version reference. build_id and deployment_id are external CI, build and deployment
references. Builder Version and Deploy UUIDs are separate identities. Use real configured values or omit them.
component_id, agent_id and agent_version_id are reported application keys. Native gen_ai.agent.*
facts, provider model names and Part relationships have their own sources.
Route credentials establish Workspace and Product tenancy. Context values are correlation claims. Keep
Environment, reported deployed-version reference, component/build/deployment, Session, Interaction, purpose,
User and DomainRun(kind, id) distinct. Business identities emit impact.session.id, impact.interaction.id
and impact.user.id. Native provider conversation, response, Trace and Span IDs remain separate. A Simulation
run or invocation ID is not a Session or Interaction ID.
Manual tool capture
Use an explicit tool span inside the owning Interaction when the application calls the tool itself. Call the real tool once and set its result on the span. Herelookup_order is the application’s normal tool.
Typed content and lazy results
Manual spans and Interactions record a successfully captured input or output as one JSON document withapplication/json MIME. Decode the value once. JSON null, false, zero and empty text have distinct values,
and a string that looks like JSON stays a string. A missing value or MIME declaration leaves typed content
unavailable. The capture state explains whether a policy or native limit omitted it.
Supported Python iterator and async-iterator results remain lazy and observe actual exhaustion, explicit
close, error or cancellation. Never-consumed or opaque framework/HTTP results do not imply successful
completion. Drain or close such work at the application’s actual observable boundary. Stopping telemetry does
not end a business Session.
Propagate native context and correlation
inject_context() combines initialized context defaults with the current scope’s overrides. It fills and
returns the supplied carrier with standard W3C traceparent/tracestate plus one bounded impact-context
value. That value is canonical compact UTF-8 JSON encoded as unpadded base64url: version 2, optional
Interaction/Session and domainRun. User attribution is not automatically propagated. A conflicting or stale
owned value raises ValueError without changing any carrier field. Use a fresh carrier for each request.
Successful shutdown removes initialized defaults.
extract_context() returns context, native_context, content-free issues and an optional explicit
transfer. Inspect issues before applying received correlation through context(propagated=...). Conflicting
Interaction, Session or Domain Run IDs from that carrier cause ValueError before the active local
correlation or native context changes. Existing application-owned native parentage is preserved. Contributor
propagation never grants completion ownership or authorizes a Product route. JavaScript uses the same
versioned wire contract. Use the version 2 headers for cross-language propagation.
Create the gateway carrier inside each actual request’s active span and pass it through the application’s
existing per-request header option. For an application-owned http.client connection, use
connection.request("POST", path, body=body, headers=impact.inject_context(request_headers)). Keep native
credentials and other request options under application control. Do not cache an injected traceparent on a
shared client: concurrent requests need their own active parent. Injection preserves existing equal values and
does not install an HTTP patcher.
Hand off completion ownership
For longer work, confirm handoff when the application receives its durable publication acknowledgement. The sender and worker below use the application’s queue and request handlers.confirm() is valid only within the active
publisher callback. Returning or raising without confirmation leaves transfer unconfirmed. A later error after
confirmation cannot reclaim completion ownership. The SDK never republishes business work.
continue_interaction requires an actual transfer carrier and defaults to preserving active native parentage.
Supply new_trace=True to start a new technical root linked to the valid received context while retaining
logical identity. An ordinary nested interaction() with the active Interaction ID raises before invoking the
inner callback. Use context() or span() for contributor work, and await the actual join inside the
application’s completion owner.
Typed context and Session ending
Optional typed context fieldschannel, locale, plan, user_type and journey_step emit the
corresponding impact.correlation.channel, .locale, .plan, .user_type and .journey_step attributes.
They use the context string bounds above and do not prescribe a vocabulary or infer values. Stable defaults
may be supplied through init(context=impact.ImpactContext(...)). Within one context, a typed field wins over
its exact canonical correlation key. An inner scope wins over outer/default values, including an inner
correlation value. Existing correlation-only values keep their validation and omission behavior.
agent_version_id continues to emit impact.agent.version.id separately from the Product’s version_id.
Supply a known terminal Session fact on the actual terminal operation, before its span or automatic owner
starts:
session_ending emits the raw impact.session.ending attribute and requires session_id in the same
submitted context. It is rejected in init defaults. Nested work inherits it for the same Session. Changing the
Session clears the inherited ending unless that scope supplies a new pair, and leaving the scope restores the
outer pair. Application-owned native trace parentage must still place the terminal operation under the
intended Session. An existing Trace keeps its native parentage if the context value changes. This field
records the supplied fact, does not close a Session or alter inferred Ending classification, and offers no
post-hoc ending API. Verify the terminal span’s raw attribute through authenticated Trace readback under that
exact Session. These typed fields and the supplied ending are not added to propagation headers or baggage.
Provenance and source references
Shared execution provenance usesimpact.execution.origin, impact.execution.input.reference and distinct
impact.<evaluation|dataset|case|experiment|replay>.id attributes. Source references use code.file.path,
code.function.name, code.line.number, impact.source.basis.id and impact.source.observed.at.
Correlation values use impact.correlation.*, matching JavaScript’s custom fields. These supplied claims do
not establish route authority or trigger source inspection. Native provider identity fields retain their own
meanings.
Automatic callsites require an explicit source root and deployment/source basis:
callsites when no trustworthy mapping is available, or set
enabled=False for a global opt-out. Explicit ImpactContext(source=...) facts remain authoritative.
Startup and lifecycle · Privacy and streaming