> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brixo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Python Quickstart

> Python Quickstart — Send Agent Traces to Brixo

**Goal:** In under 10 minutes, send rich agent traces from your Python app to **Brixo** and unlock customer analytics.

***

## TL;DR

1. Create an account @ [https://app.brixo.com/sign\_up](https://app.brixo.com/sign_up)
2. Grab an API key and add it to your environment
3. Install the Brixo SDK
4. Instrument your agent application
5. Watch traces appear in Brixo's Live View and confirm they look good

***

## Prerequisites

* Python 3.10+
* Brixo account + API key

***

## Step 1 — Create an account

Create an account @ [https://app.brixo.com/sign\_up](https://app.brixo.com/sign_up)

## Step 2 — Get an API key and add it to your environment

Generate an API key from the in-app instruction page and set the **BRIXO\_API\_KEY** environment variable to it:

```bash theme={null}
export BRIXO_API_KEY=<your_api_key>
```

## Step 3 — Install the Brixo SDK

```bash theme={null}
pip install brixo
```

***

## Step 4 — Instrument your agent application

The typical flow is:

1. Initialize Brixo once at application startup
2. Wrap each *user interaction* with `@Brixo.interaction`
3. Attach context (user, account, session, input, output)
4. Let the interaction finish so traces can be flushed

***

### About `user.id`

Brixo is designed to use `user.id` as a stable identifier from your system of record—most commonly a CRM such as Salesforce.

Using a UID that can be mapped to a CRM record enables Brixo to:

* Automatically enrich interactions with CRM metadata when Brixo's CRM connector is enabled
* Power segmentation by plan, industry, territory, role, lifecycle stage, and more
* Keep analytics consistent across agents, channels, and tools
* Avoid duplicating or syncing customer data manually

In most agent runtimes, the most reliable identifier available is the **user’s email address**.

Brixo recommends using:

* `user.id`: the user’s **email**

If you later connect your CRM via Brixo's connector, Brixo can enrich your interactions with customer metadata based on these identifiers—without changing your instrumentation. 🙌

## Example

Below is a minimal but complete example that instruments a single agent interaction loop.

Create a file called `main.py`:

```python theme={null}
# --- Brixo SDK import ---
# Import the Brixo SDK so we can instrument and send interaction traces to Brixo.
from brixo import Brixo
from my_agent import agent

# --- Brixo interaction boundary ---
# Mark ONE bounded user interaction (one request → one response) so Brixo can group
# spans/attributes into a single trace and flush it when this function returns.

@Brixo.interaction("Main Agent Execution")
def handle_user_input(user_input: str):

    # --- Brixo context start ---
    # Attach contextual metadata to the current trace
    Brixo.begin_context(
        user={
          "id": "jane.doe@acme.com", # Stable user identifier (e.g. email)
          "name": "Jane Doe"
        }, 
        account={
          "id": "org_7f3a2c91", # Stable account/tenant identifier
          "name": "ACME, Inc."
        },
        session_id="session-123",
        metadata={"foo": "bar"},
        message_id="assistant-msg-123",
        input=user_input,
    )

    response = agent.invoke(
        {"messages": [{"role": "user", "content": user_input}]}
    )

    handle_agent_response(response)
    
    
def handle_agent_response(response):
    """Extracts the final agent output and updates the trace."""

    final_text = response["messages"][-1]["content"]

    # --- Brixo context end ---
    # Explicitly close the context (currently a no‑op safety guard)
    Brixo.end_context(output=final_text)


def main():
    # --- Brixo SDK initialization ---
    # Initialize once at startup, before any instrumented code runs.    
    Brixo.init(
        app_name="my-agent",
        environment="production",
    )

    while True:
        user_input = input("User: ")
        handle_user_input(user_input)


if __name__ == "__main__":
    main()
```

Run the example:

```
python main.py
```

# Key Concepts

## Initialization

### `Brixo.init(...)`

Initializes the Brixo SDK **once at application startup**. This sets runtime-wide settings (like `app_name` and `environment`) and configures the SDK so that any subsequent instrumented code can emit traces.

**When to call it:**

* Call **exactly once**, as early as possible in your app startup.
* Call it **before** any instrumented code runs (before your first `@Brixo.interaction` executes).

```python theme={null}
Brixo.init(
    app_name="my-agent",
    environment="production",
)
```

## Initialization Attributes

Some attributes apply to the *application runtime* (not a single interaction). These are configured once via `Brixo.init(...)` and automatically apply to all interactions.

### `app_name` (**required**)

Name of the agent application

```jsx theme={null}
Brixo.init(
    app_name="my-agent",
    environment="production",
)
```

### `environment` (**required**)

Execution environment for this app/runtime.

```python theme={null}
Brixo.init(
    app_name="my-agent",
    environment="production",
)
```

Typical values:

* `development`
* `staging`
* `production`

## Interaction Boundaries

### `@Brixo.interaction(name)`

Marks a single, bounded **user interaction** (one request → one response). Brixo uses this boundary to group spans/attributes into one trace and flush it when the function returns.

```python theme={null}
@Brixo.interaction("Main Agent Execution")
def handle_user_input(user_input: str):
    ...
```

* `name` (required): Descriptive interaction name shown in Brixo
* Use **one interaction per user request**
* The decorated function must **terminate** (no infinite loops)
* Choose descriptive names — they improve trace readability

***

### `Brixo.begin_context(...)`

Starts an interaction context and attaches initial attributes.

Typical use cases:

* Attach `user`, `account`, `session_id`
* Attach `message_id` so assistant messages can be linked to [Signals HTTP API](/ingestion/http-api) feedback
* Record raw user `input`

```python theme={null}
Brixo.begin_context(
    user={
		"id": "jane.doe@acme.com", # Stable user identifier (e.g. email)
		"name": "Jane Doe"
	},
    account={
		"id": "org_7f3a2c91", # Stable account/tenant identifier
		"name": "ACME, Inc."
	},
    session_id="session-abc-123",
    message_id="assistant-msg-123",
    input=user_input,
)
```

***

### `Brixo.update_context(...)`

Adds or updates context attributes **while the interaction is in progress**.

Typical use cases:

* Derived metrics
* Tool results
* Partial summaries
* Intermediate state

```python theme={null}
Brixo.update_context(
    metadata={"tools_used": ["search", "calculator"]}
)
```

***

### `Brixo.end_context(...)`

Adds or updates context attributes and **explicitly closes** the interaction.

Typical use cases:

* Attach final `output`
* Add outcome-related metadata

```python theme={null}
Brixo.end_context(
    output=final_text
)
```

## Context Attributes (Per Interaction)

Brixo interactions support a common set of **context attributes** that describe *who* the interaction is for, *what* happened, and *what the outcome was*.

These attributes can be set or updated at **any point during an interaction lifecycle** using:

* `Brixo.begin_context(...)`
* `Brixo.update_context(...)`
* `Brixo.end_context(...)`

> You do not need to provide all attributes up front.
>
> A common pattern is to attach identifiers and input early, and attach derived data or outputs later.

***

### Supported Context Attributes

**Required for every interaction:**

* `user.id` and `user.name`
* `account.id` and `account.name`
* `session_id`
* `input`
* `output`

> input is typically set in `Brixo.begin_context(...)`, and output is typically set in `Brixo.end_context(...)`. You may set them via `Brixo.update_context(...)` as long as they are present before the interaction finishes.

**Optional when you want to link assistant messages to feedback signals:**

* `message_id`

### `user`

Identifies the end user interacting with the agent.

```python theme={null}
user = {
    "id": "jane.doe@acme.com",
    "name": "Jane Doe"
}
```

* `id` (required): Stable internal identifier for the user

  Typically an email address, which can be mapped to a CRM record (e.g. Salesforce) when a connector is enabled.
* `name` (required): Display name

***

### `account`

Identifies the customer, tenant, or organization associated with the interaction.

```python theme={null}
account = {
    "id": "org_7f3a2c91",
    "name": "ACME, Inc."
}
```

* `id` (required): Stable internal identifier for the account or customer
* `name` (required): Human-readable display name

***

### `session_id`

Logical identifier that groups multiple interactions into a session.

```python theme={null}
session_id = "session-abc-123"
```

* Use the same `session_id` across multiple interactions to enable session-level analysis

***

### `input`

Raw user input that initiated the interaction.

```python theme={null}
input = "Reset my password"
```

* **Required** for every interaction
* Typically set at the beginning of an interaction
* Used for analytics, debugging, and replay

***

### `message_id`

Customer-defined assistant message ID used to link the final traced assistant message to feedback signals sent through the [Signals HTTP API](/ingestion/http-api).

```python theme={null}
message_id = "assistant-msg-123"
```

* Optional: `str` or `None`
* This will usually be your internal assistant message ID from your system
* When you send a message-level feedback signal to `POST /v1/messages/:id/signals`, `:id` must match the `message_id` you sent during instrumentation

***

### `output`

Final agent output for the interaction.

```python theme={null}
output = "I've sent you a password reset link."
```

* **Required** for every interaction
* Typically set via `Brixo.end_context(...)`
* Represents the resolved response returned to the user

***

### `metadata`

Arbitrary structured key-value data associated with the interaction.

```python theme={null}
metadata = {
    "channel": "web",
    "plan": "enterprise",
    "experiment": "agent-v2"
}
```

* Useful for custom segmentation and filtering
* Values must be JSON-serializable

***

## Best Practices

* **One interaction = one user request**
* Keep interaction functions short and bounded
* Use descriptive interaction names
* Attach inputs early and outputs late
* Initialize Brixo early at startup; if you rely on auto-instrumentation, import those libraries after `Brixo.init(...)`
* Use `update_context` freely — it does not end the interaction
* Close every interaction so traces can be flushed and analyzed

## **Support**

If you have questions or run into issues:

* Check the Brixo [Live View](https://app.brixo.com/traces/live) for trace visibility
* Reach out to the Brixo team at [hello@brixo.com](mailto:hello@brixo.com)

Happy instrumenting 🚀