The infrastructure for long-horizon vertical agents.
Introspection is the infrastructure for long-horizon vertical agents, powered by Pi. Define an agent as a Recipe — agents, skills, policies, and evals in plain source you own in Git — deploy it to a governed per-customer Runtime, and improve it in production with conversations, observations, judges, and experiments.
This is the Python SDK: run tasks against a deployed runtime, stream their output, and record what users thought of the result.
Install
uv add introspection-sdk
# or
pip install introspection-sdk
Run a task
import asyncio
from introspection_sdk import AsyncIntrospectionClient
async def main() -> None:
async with AsyncIntrospectionClient() as client: # token from INTROSPECTION_TOKEN
runner = await client.runtimes("customer-agent").run()
async with runner:
run = await runner.tasks.start(prompt="Say hello in one sentence.")
async for event in run.stream():
print(event)
asyncio.run(main())
Or wait for the finished answer instead of streaming:
run = await runner.tasks.start(prompt="Summarize my open tickets.")
print(await run.text())
Continue the same task with a follow-up run:
follow_up = await runner.tasks.runs.create(
str(run.run.task_id),
kind="prompt",
prompt={"text": "Now draft the reply."},
)
print(await follow_up.text())
IntrospectionClient is the synchronous twin with the same surface — drop the
awaits and use for instead of async for.
See Tasks and streaming for reconnects, interrupts, and cancellation.
Record feedback
Install the OpenTelemetry extra, then attach the outcome to the conversation the agent produced:
pip install 'introspection-sdk[otel]'
from introspection_sdk import IntrospectionLogs
logs = IntrospectionLogs(service_name="support-api")
with logs.identify("user_123", traits={"plan": "pro"}):
with logs.set_conversation(conversation_id):
logs.feedback("thumbs_up", comments="The answer solved it")
logs.track("case_closed", {"source": "web"})
logs.shutdown()
feedback records how a result landed, track records a product event, and
identify attaches who it was.
See Product signals for the full surface, and
docs/otel.md for the OTel wiring.
Read what happened
A finished task leaves a durable conversation:
async for summary in runner.conversations.list(limit=20):
print(summary.id, summary.usage.total_tokens, summary.cost.usd)
The runner also exposes files, shares, events, and metrics.
See Production evidence for transcripts,
typed events, and metrics queries, Files and shares
for durable inputs and grants, and examples/
for end-to-end scripts.
Environment variables
export INTROSPECTION_TOKEN="intro_xxx"
export INTROSPECTION_SERVICE_NAME="my-service" # optional
export INTROSPECTION_LOG_LEVEL="debug" # optional
Documentation
- Python quickstart
- Tasks and streaming
- Files and shares
- Production evidence
- Product signals
- Platform operations
- Python SDK reference
- Authentication
License
Apache-2.0
1 maintainer
Metadata
1 maintainer
Release files for introspection-sdk 0.16.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| introspection_sdk-0.16.0.tar.gz | 92.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| introspection_sdk-0.16.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 216.4 kB
Release files / introspection_sdk-0.16.0.tar.gz
| Download URL | introspection_sdk-0.16.0.tar.gz |
|---|---|
| Size | 92.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ac886033e8300b661cb5d269838c83f8686f08c7b873195e7e0fffea3d2b8f05
|
|
BLAKE2b-256 checksum How to use checksums |
22e141c50ef112edb14696227098447595702797fa332850decf47259fdbd86f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 13, 2026.
Transparency logRelease files / introspection_sdk-0.16.0-py3-none-any.whl
| Download URL | introspection_sdk-0.16.0-py3-none-any.whl |
|---|---|
| Size | 123.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
017f2ebe2eb6d9e1a2a88e18703c5cec38bb76c46960e3a038f0f0ced2d1e47d
|
|
BLAKE2b-256 checksum How to use checksums |
ca08931c869adb84018ce87d0235e0e71731042c03ef60a534d6d7f6e743c692
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 13, 2026.
Transparency log
