​

TL;DR

1. Create an account @ 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

​

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

export BRIXO_API_KEY=<your_api_key>

​

Step 3 — Install the Brixo SDK

pip install brixo

​

Step 4 — Instrument your agent application

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

• 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

• user.id: the user’s email

​

Example

# --- 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": "[email protected]", # 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"},
        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()

python main.py

​

Key Concepts

​

Initialization

​

Brixo.init(...)

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

Brixo.init(
    app_name="my-agent",
    environment="production",
)

​

Initialization Attributes

​

app_name (required)

Brixo.init(
    app_name="my-agent",
    environment="production",
)

​

environment (required)

Brixo.init(
    app_name="my-agent",
    environment="production",
)

• development
• staging
• production

​

Interaction Boundaries

​

@Brixo.interaction(name)

@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(...)

• Attach user, account, session_id
• Record raw user input

Brixo.begin_context(
    user={
		"id": "[email protected]", # 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",
    input=user_input,
)

​

Brixo.update_context(...)

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

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

​

Brixo.end_context(...)

• Attach final output
• Add outcome-related metadata

Brixo.end_context(
    output=final_text
)

​

Context Attributes (Per Interaction)

• 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

• 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.

​

user

user = {
    "id": "[email protected]",
    "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

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

session_id = "session-abc-123"

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

​

input

input = "Reset my password"

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

​

output

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

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

• Check the Brixo Live View for trace visibility
• Reach out to the Brixo team at [email protected]