introspection-sdk 0.15.1

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