SDK Documentation

1. Track LLM Calls

“I want to see cost, tokens, and latency for my LLM usage.”

import magenta
from openai import OpenAI

magenta.init(api_key="...", project_id="...", user_id="...")
magenta.track_llm_calls()  # Enable automatic tracking

client = OpenAI()
response = client.chat.completions.create(...)  # Auto-tracked!

2. Track Agents

“I want to understand what each agent did, end-to-end.”

import magenta
from openai import OpenAI

magenta.init(api_key="...", project_id="...", user_id="...")
magenta.track_llm_calls()

client = OpenAI()

with magenta.run("Research Task"):
    with magenta.agent("Researcher", "gpt-4"):
        magenta.event("input", {"query": "AI trends"})

        response = client.chat.completions.create(
            model="gpt-4",
            messages=[{"role": "user", "content": "AI trends 2024"}],
        )

        magenta.event("output", {"result": response.choices[0].message.content})

magenta.init()

Initialize the SDK. Call once at startup.

magenta.init(
    api_key: str,
    project_id: str,
    user_id: str,
    endpoint: str = "localhost:3000",  # optional
    capture_llm_response: bool = False,  # optional
)

magenta.track_llm_calls()

Enable automatic LLM call tracking.

magenta.track_llm_calls()  # Enable globally

magenta.run(name, objective?)

Execute code in a run context.

with magenta.run("Task Name", objective="optional goal"):
    # All agent calls inside are traced
    pass

magenta.agent(name, model)

Execute code in an agent trace.

with magenta.agent("Coder", "gpt-4"):
    magenta.event("input", {"task": "Write code"})
    # ... do work ...
    magenta.event("output", {"code": "..."})

Nested agents are linked automatically.

magenta.event(type, data)

Log an event (context auto-detected).

magenta.event("input", {"query": "..."})
magenta.event("output", {"result": "..."})
magenta.event("tool_call", {"tool": "search"})
magenta.event("state", {"status": "processing"})
magenta.event("error", {"message": "..."})

magenta.set_outcome(text)

Set the outcome of the current run.

magenta.set_outcome("Completed successfully with 3 results")

Reporting a Vulnerability

• Do not open a public GitHub issue for security vulnerabilities
• Email the security team with details of the vulnerability
• Include steps to reproduce the issue if possible
• Allow reasonable time for a fix before public disclosure

Security Considerations

Data Privacy:

• No prompts/outputs logged by default - LLM response capture is opt-in via capture_llm_response=True
• No environment variables logged - Only explicitly passed data is transmitted
• Sensitive data is user-controlled - Use magenta.event() carefully to avoid logging secrets

Network Security:

• All data is sent over HTTPS in production
• API keys are passed via Authorization header, not logged
• Failed requests do not expose sensitive data in error messages

Best Practices:

• Never log secrets - Don't pass API keys, passwords, or tokens to magenta.event()
• Review logged data - Be aware of what data your events contain
• Use environment variables - Store API keys in environment variables, not code
• Secure your endpoint - Ensure your backend endpoint uses HTTPS

Resource Attributes

Set on the OpenTelemetry Resource and apply to all spans:

Run Attributes

Set on root spans that represent execution runs:

Agent Attributes

Set on agent trace spans:

Event Types

Valid values for magenta.event.type:

Our Standards

Positive behaviors:

• Being respectful and considerate in communications
• Providing constructive feedback
• Focusing on what's best for the community
• Showing empathy towards others

Unacceptable behaviors:

• Harassment, discrimination, or offensive comments
• Personal attacks or trolling
• Publishing others' private information
• Other conduct inappropriate for a professional setting

Enforcement

Project maintainers may remove, edit, or reject comments, commits, code, and other contributions that violate this Code of Conduct. Repeated violations may result in a ban from the project.