# agentinsight/agentinsight-sdk-python architecture

> Architecture diagram of the GitHub repository agentinsight/agentinsight-sdk-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/agentinsight/agentinsight-sdk-python
- Repository: https://github.com/agentinsight/agentinsight-sdk-python

## Overview

AgentInsight is a Python SDK for LLM observability, tracing, evaluation, and prompt management. Users initialize a client, instrument LLM or application work, and export trace data to the AgentInsight platform; they can then score traces or run dataset experiments and batch evaluations. OpenAI and LangChain instrumentation, manual spans, context propagation, prompt management, and asynchronous media/score processing are distinct capabilities. Edges rely on README workflow statements and SOURCE INDEX references; unsampled implementation details are not assumed.

Main entry points: [`agentinsight/_client/client.py`](https://github.com/agentinsight/agentinsight-sdk-python/blob/main/agentinsight/_client/client.py) (AgentInsight client), [`agentinsight/_client/resource_manager.py`](https://github.com/agentinsight/agentinsight-sdk-python/blob/main/agentinsight/_client/resource_manager.py) (Tracer runtime), [`agentinsight/api`](https://github.com/agentinsight/agentinsight-sdk-python/tree/main/agentinsight/api) (Platform API), [`agentinsight/__init__.py`](https://github.com/agentinsight/agentinsight-sdk-python/blob/main/agentinsight/__init__.py) (Initialize SDK)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_instrumentation["Instrumentation"]
  node_initialize["Initialize SDK<br/>[__init__.py]"]
  node_openai_integration["OpenAI instrumentation<br/>[openai.py]"]
  node_langchain_integration["LangChain handler<br/>[CallbackHandler.py]"]
  node_observe["Observe decorator<br/>[observe.py]"]
end

subgraph group_telemetry["Telemetry runtime"]
  node_client["AgentInsight client<br/>[client.py]"]
  node_span["Span operations<br/>[span.py]"]
  node_propagation["Context propagation<br/>[propagation.py]"]
  node_resource_manager["Tracer runtime"]
  node_media_tasks["Media upload<br/>[media_manager.py]"]
  node_score_tasks["Score ingestion"]
end

subgraph group_evaluation["Evaluation workflows"]
  node_experiments["Dataset experiments<br/>[experiment.py]"]
  node_batch_eval["Batch evaluation"]
  node_prompt_cache["Prompt management<br/>[prompt_cache.py]"]
end

subgraph group_platform_api["Platform API"]
  node_api["Platform API"]
  node_api_transport["HTTP transport<br/>[client_wrapper.py]"]
end

node_developer(("Application developer"))
node_platform[("AgentInsight platform")]
node_llm_provider(("LLM provider"))

node_developer -->|"configures"| node_initialize
node_developer -->|"instruments calls"| node_openai_integration
node_developer -->|"registers handler"| node_langchain_integration
node_developer -->|"decorates work"| node_observe
node_openai_integration -->|"wraps calls"| node_llm_provider
node_langchain_integration -->|"creates observations"| node_client
node_observe -->|"traces functions"| node_client
node_initialize -->|"provides client"| node_client
node_client -->|"creates spans"| node_span
node_client -->|"uses propagation"| node_propagation
node_client -->|"uses tracer runtime"| node_resource_manager
node_resource_manager -->|"starts workers"| node_media_tasks
node_resource_manager -.->|"starts workers"| node_score_tasks
node_client -->|"uses API"| node_api
node_api -.->|"uses transport"| node_api_transport
node_api -->|"sends requests"| node_platform
node_resource_manager -.->|"exports telemetry"| node_platform
node_client -.->|"supports experiments"| node_experiments
node_experiments -->|"supports evaluation"| node_batch_eval
node_batch_eval -->|"fetches and scores"| node_client
node_client -->|"uses prompt cache"| node_prompt_cache
node_prompt_cache -.->|"retrieves prompts"| node_platform

click node_initialize "https://github.com/agentinsight/agentinsight-sdk-python/blob/main/agentinsight/__init__.py"
click node_openai_integration "https://github.com/agentinsight/agentinsight-sdk-python/blob/main/agentinsight/openai.py"
click node_langchain_integration "https://github.com/agentinsight/agentinsight-sdk-python/blob/main/agentinsight/langchain/CallbackHandler.py"
click node_observe "https://github.com/agentinsight/agentinsight-sdk-python/blob/main/agentinsight/_client/observe.py"
click node_client "https://github.com/agentinsight/agentinsight-sdk-python/blob/main/agentinsight/_client/client.py"
click node_span "https://github.com/agentinsight/agentinsight-sdk-python/blob/main/agentinsight/_client/span.py"
click node_propagation "https://github.com/agentinsight/agentinsight-sdk-python/blob/main/agentinsight/_client/propagation.py"
click node_resource_manager "https://github.com/agentinsight/agentinsight-sdk-python/blob/main/agentinsight/_client/resource_manager.py"
click node_media_tasks "https://github.com/agentinsight/agentinsight-sdk-python/blob/main/agentinsight/_task_manager/media_manager.py"
click node_score_tasks "https://github.com/agentinsight/agentinsight-sdk-python/blob/main/agentinsight/_task_manager/score_ingestion_consumer.py"
click node_experiments "https://github.com/agentinsight/agentinsight-sdk-python/blob/main/agentinsight/experiment.py"
click node_batch_eval "https://github.com/agentinsight/agentinsight-sdk-python/blob/main/agentinsight/batch_evaluation.py"
click node_prompt_cache "https://github.com/agentinsight/agentinsight-sdk-python/blob/main/agentinsight/_utils/prompt_cache.py"
click node_api "https://github.com/agentinsight/agentinsight-sdk-python/tree/main/agentinsight/api"
click node_api_transport "https://github.com/agentinsight/agentinsight-sdk-python/blob/main/agentinsight/api/core/client_wrapper.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_initialize,node_openai_integration,node_langchain_integration,node_observe toneBlue
class node_client,node_span,node_propagation,node_resource_manager,node_media_tasks,node_score_tasks,node_platform toneAmber
class node_experiments,node_batch_eval,node_prompt_cache toneMint
class node_api,node_api_transport toneRose
class node_developer,node_llm_provider toneIndigo
```

## Components

### Instrumentation

- [Initialize SDK](https://github.com/agentinsight/agentinsight-sdk-python/blob/main/agentinsight/__init__.py): `agentinsight/__init__.py`
- [OpenAI instrumentation](https://github.com/agentinsight/agentinsight-sdk-python/blob/main/agentinsight/openai.py): `agentinsight/openai.py`
- [LangChain handler](https://github.com/agentinsight/agentinsight-sdk-python/blob/main/agentinsight/langchain/CallbackHandler.py): `agentinsight/langchain/CallbackHandler.py`
- [Observe decorator](https://github.com/agentinsight/agentinsight-sdk-python/blob/main/agentinsight/_client/observe.py): `agentinsight/_client/observe.py`

### Telemetry runtime

- [AgentInsight client](https://github.com/agentinsight/agentinsight-sdk-python/blob/main/agentinsight/_client/client.py): `agentinsight/_client/client.py`
- [Span operations](https://github.com/agentinsight/agentinsight-sdk-python/blob/main/agentinsight/_client/span.py): `agentinsight/_client/span.py`
- [Context propagation](https://github.com/agentinsight/agentinsight-sdk-python/blob/main/agentinsight/_client/propagation.py): `agentinsight/_client/propagation.py`
- [Tracer runtime](https://github.com/agentinsight/agentinsight-sdk-python/blob/main/agentinsight/_client/resource_manager.py): `agentinsight/_client/resource_manager.py`
- [Media upload](https://github.com/agentinsight/agentinsight-sdk-python/blob/main/agentinsight/_task_manager/media_manager.py): `agentinsight/_task_manager/media_manager.py`
- [Score ingestion](https://github.com/agentinsight/agentinsight-sdk-python/blob/main/agentinsight/_task_manager/score_ingestion_consumer.py): `agentinsight/_task_manager/score_ingestion_consumer.py`

### Evaluation workflows

- [Dataset experiments](https://github.com/agentinsight/agentinsight-sdk-python/blob/main/agentinsight/experiment.py): `agentinsight/experiment.py`
- [Batch evaluation](https://github.com/agentinsight/agentinsight-sdk-python/blob/main/agentinsight/batch_evaluation.py): `agentinsight/batch_evaluation.py`
- [Prompt management](https://github.com/agentinsight/agentinsight-sdk-python/blob/main/agentinsight/_utils/prompt_cache.py): `agentinsight/_utils/prompt_cache.py`

### Platform API

- [Platform API](https://github.com/agentinsight/agentinsight-sdk-python/tree/main/agentinsight/api): `agentinsight/api`
- [HTTP transport](https://github.com/agentinsight/agentinsight-sdk-python/blob/main/agentinsight/api/core/client_wrapper.py): `agentinsight/api/core/client_wrapper.py`

### Other components

- **Application developer**
- **AgentInsight platform**
- **LLM provider**

## Connections

- Application developer → Initialize SDK: configures
- Application developer → OpenAI instrumentation: instruments calls
- Application developer → LangChain handler: registers handler
- Application developer → Observe decorator: decorates work
- OpenAI instrumentation → LLM provider: wraps calls
- LangChain handler → AgentInsight client: creates observations (evidence: `agentinsight/langchain/CallbackHandler.py`)
- Observe decorator → AgentInsight client: traces functions
- Initialize SDK → AgentInsight client: provides client (evidence: `agentinsight/__init__.py`)
- AgentInsight client → Span operations: creates spans (evidence: `agentinsight/_client/client.py`)
- AgentInsight client → Context propagation: uses propagation (evidence: `agentinsight/_client/client.py`)
- AgentInsight client → Tracer runtime: uses tracer runtime (evidence: `agentinsight/_client/client.py`)
- Tracer runtime → Media upload: starts workers (evidence: `agentinsight/_client/resource_manager.py`)
- Tracer runtime → Score ingestion: starts workers (evidence: `agentinsight/_client/resource_manager.py`)
- AgentInsight client → Platform API: uses API (evidence: `agentinsight/_client/client.py`)
- Platform API → HTTP transport: uses transport (evidence: `agentinsight/api/annotation_queues/raw_client.py`)
- Platform API → AgentInsight platform: sends requests
- Tracer runtime → AgentInsight platform: exports telemetry
- AgentInsight client → Dataset experiments: supports experiments (evidence: `agentinsight/_client/client.py`)
- Dataset experiments → Batch evaluation: supports evaluation (evidence: `agentinsight/experiment.py`)
- Batch evaluation → AgentInsight client: fetches and scores (evidence: `agentinsight/batch_evaluation.py`)
- AgentInsight client → Prompt management: uses prompt cache (evidence: `agentinsight/_client/client.py`)
- Prompt management → AgentInsight platform: retrieves prompts
