The infrastructure for long-horizon vertical agents.

Website PyPI version License Follow on X

[Introspection](https://introspection.dev) is the infrastructure for long-horizon vertical agents, powered by Pi. Define an agent as a [Recipe](https://pi.recipes) — 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

License

Apache-2.0

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.15.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for brightsparc from gravatar.com brightsparc

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.11

Provides Extra

arrow dev otel test

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

introspection_sdk-0.15.0.tar.gz (86.0 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

introspection_sdk-0.15.0-py3-none-any.whl (115.1 kB view details)

Uploaded Python 3

File details

Details for the file introspection_sdk-0.15.0.tar.gz.

File metadata

  • Download URL: introspection_sdk-0.15.0.tar.gz
  • Upload date:
  • Size: 86.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for introspection_sdk-0.15.0.tar.gz
Algorithm Hash digest
SHA256 d337890feeaa3a122e7606f7d2d7f3bf66a710dca2d2ce0e9b261c7b1fc01d69
MD5 dd0a8b9473bd60e076da716084521044
BLAKE2b-256 7506140c5f36614ef5a8adbead323a2a81764c86387e8d91077196137f1ea421

See more details on using hashes here.

Provenance

The following attestation bundles were made for introspection_sdk-0.15.0.tar.gz:

Publisher: publish.yml on introspection-org/introspection-python-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file introspection_sdk-0.15.0-py3-none-any.whl.

File metadata

File hashes

Hashes for introspection_sdk-0.15.0-py3-none-any.whl
Algorithm Hash digest
SHA256 35767f2212e39defc15c2d65990ae07b54fdca825316190a7d84e0e6266625d7
MD5 a158f18946513fdd87e9e37a0870e107
BLAKE2b-256 d14598fb5e8786b90822e22eeb0662d24dd7d5ba836f84b1c8db101dc9f83c91

See more details on using hashes here.

Provenance

The following attestation bundles were made for introspection_sdk-0.15.0-py3-none-any.whl:

Publisher: publish.yml on introspection-org/introspection-python-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page