mirror of
https://github.com/hanzoai/insights.git
synced 2026-11-02 14:32:45 +00:00
zeekay
bc4ddf332b
Mechanically re-derived: bin/debrand runs over a fresh import of posthog/posthog@fa1a9a60d4 (2026-08-06). The pipeline (.hanzo/workflows), the Dockerfiles and bin/docker* entrypoints, compose files, LLM.md and the squashed initial migration are restored from the shipped tree, same as the previous import. The prune's import-closure guard kept 21 products the new core now imports; dropping them is a refactor now, recorded rather than forced.
217 lines
9.2 KiB
TypeScript
217 lines
9.2 KiB
TypeScript
import { OnboardingComponentsContext, createInstallation } from 'scenes/onboarding/shared/OnboardingDocsContentWrapper'
|
|
|
|
import { StepDefinition } from '../steps'
|
|
|
|
export const getOpenAIAgentsSteps = (ctx: OnboardingComponentsContext): StepDefinition[] => {
|
|
const { CodeBlock, CalloutBox, Markdown, Blockquote, dedent, snippets } = ctx
|
|
|
|
const NotableGenerationProperties = snippets?.NotableGenerationProperties
|
|
|
|
return [
|
|
{
|
|
title: 'Install the Insights SDK',
|
|
badge: 'required',
|
|
content: (
|
|
<>
|
|
<Markdown>Setting up analytics starts with installing the Insights Python SDK.</Markdown>
|
|
|
|
<CodeBlock
|
|
language="bash"
|
|
code={dedent`
|
|
pip install insights
|
|
`}
|
|
/>
|
|
</>
|
|
),
|
|
},
|
|
{
|
|
title: 'Install the OpenAI Agents SDK',
|
|
badge: 'required',
|
|
content: (
|
|
<>
|
|
<Markdown>
|
|
Install the OpenAI Agents SDK. Insights instruments your agent runs by registering a tracing
|
|
processor. The Insights SDK **does not** proxy your calls.
|
|
</Markdown>
|
|
|
|
<CodeBlock
|
|
language="bash"
|
|
code={dedent`
|
|
pip install openai-agents
|
|
`}
|
|
/>
|
|
|
|
<CalloutBox type="fyi" icon="IconInfo" title="Proxy note">
|
|
<Markdown>
|
|
These SDKs **do not** proxy your calls. They only fire off an async call to Insights in the
|
|
background to send the data. You can also use AI observability with other SDKs or our API,
|
|
but you will need to capture the data in the right format. See the schema in the [manual
|
|
capture section](https://hanzo.ai/docs/ai-observability/installation/manual-capture) for
|
|
more details.
|
|
</Markdown>
|
|
</CalloutBox>
|
|
</>
|
|
),
|
|
},
|
|
{
|
|
title: 'Initialize Insights tracing',
|
|
badge: 'required',
|
|
content: (
|
|
<>
|
|
<Markdown>
|
|
Initialize Insights with your project token and host from [your project
|
|
settings](https://app.hanzo.ai/settings/project). Then call `instrument()` to register
|
|
Insights tracing with the OpenAI Agents SDK. This automatically captures all agent traces, spans,
|
|
and LLM generations.
|
|
</Markdown>
|
|
|
|
<CodeBlock
|
|
language="python"
|
|
code={dedent`
|
|
from insights import Insights
|
|
from insights.ai.openai_agents import instrument
|
|
|
|
insights = Insights(
|
|
"<ph_project_token>",
|
|
host="<ph_client_api_host>"
|
|
)
|
|
|
|
instrument(
|
|
client=insights,
|
|
distinct_id=lambda trace: (trace.metadata or {}).get("insights_distinct_id"),
|
|
privacy_mode=False, # optional
|
|
groups={"company": "company_id_in_your_db"}, # optional
|
|
)
|
|
`}
|
|
/>
|
|
|
|
<Blockquote>
|
|
<Markdown>
|
|
**Note:** If you want to capture LLM events anonymously, **do not** pass a distinct ID —
|
|
here or per run. See our docs on [anonymous vs identified
|
|
events](https://hanzo.ai/docs/data/anonymous-vs-identified-events) to learn more.
|
|
</Markdown>
|
|
</Blockquote>
|
|
</>
|
|
),
|
|
},
|
|
{
|
|
title: 'Run your agents',
|
|
badge: 'required',
|
|
content: (
|
|
<>
|
|
<Markdown>
|
|
{dedent`
|
|
Run your OpenAI agents as normal. Insights automatically captures \`$ai_generation\`
|
|
events for LLM calls and \`$ai_span\` events for agent execution, tool calls, and
|
|
handoffs. Pass the user and conversation on the run's \`RunConfig\`:
|
|
|
|
- \`group_id\` groups the run's traces into a conversation — it becomes \`$ai_session_id\`.
|
|
- \`trace_metadata["insights_distinct_id"]\` attributes the run's events to a user — the
|
|
\`distinct_id\` lambda from the previous step reads it off each trace. Any other
|
|
\`trace_metadata\` keys land on the trace as \`$ai_trace_metadata\`.
|
|
|
|
The example below defines a tool and lets the agent call it.
|
|
`}
|
|
</Markdown>
|
|
|
|
<CodeBlock
|
|
language="python"
|
|
code={dedent`
|
|
from agents import Agent, Runner, RunConfig, function_tool
|
|
|
|
@function_tool
|
|
def get_weather(city: str) -> str:
|
|
"""Get the weather for a city."""
|
|
return f"The weather in {city} is sunny, 72F"
|
|
|
|
agent = Agent(
|
|
name="Assistant",
|
|
instructions="You are a helpful assistant.",
|
|
tools=[get_weather],
|
|
)
|
|
|
|
result = Runner.run_sync(
|
|
agent,
|
|
"What's the weather in Paris?",
|
|
run_config=RunConfig(
|
|
group_id="conversation_abc",
|
|
trace_metadata={"insights_distinct_id": "user_123"},
|
|
),
|
|
)
|
|
print(result.final_output)
|
|
`}
|
|
/>
|
|
|
|
<Markdown>
|
|
{dedent`
|
|
You can expect captured \`$ai_generation\` events to have the following properties:
|
|
`}
|
|
</Markdown>
|
|
|
|
{NotableGenerationProperties && <NotableGenerationProperties />}
|
|
</>
|
|
),
|
|
},
|
|
{
|
|
title: 'Multi-agent and tool usage',
|
|
badge: 'optional',
|
|
content: (
|
|
<>
|
|
<Markdown>
|
|
{dedent`
|
|
Insights captures the full trace hierarchy for complex agent workflows, including
|
|
handoffs between multiple agents.
|
|
`}
|
|
</Markdown>
|
|
|
|
<CodeBlock
|
|
language="python"
|
|
code={dedent`
|
|
from agents import Agent, Runner, function_tool
|
|
|
|
@function_tool
|
|
def get_weather(city: str) -> str:
|
|
"""Get the weather for a city."""
|
|
return f"The weather in {city} is sunny, 72F"
|
|
|
|
weather_agent = Agent(
|
|
name="WeatherAgent",
|
|
instructions="You help with weather queries.",
|
|
tools=[get_weather]
|
|
)
|
|
|
|
triage_agent = Agent(
|
|
name="TriageAgent",
|
|
instructions="Route weather questions to the weather agent.",
|
|
handoffs=[weather_agent]
|
|
)
|
|
|
|
result = Runner.run_sync(triage_agent, "What's the weather in San Francisco?")
|
|
`}
|
|
/>
|
|
|
|
<Markdown>
|
|
{dedent`
|
|
This captures:
|
|
- Agent spans for \`TriageAgent\` and \`WeatherAgent\`
|
|
- Handoff spans showing the routing between agents
|
|
- Tool spans for \`get_weather\` function calls
|
|
- Generation spans for all LLM calls
|
|
`}
|
|
</Markdown>
|
|
|
|
<Markdown>
|
|
{dedent`
|
|
As with the single-agent example above, Insights captures every span in that list
|
|
automatically. You write no extra code for the handoff itself.
|
|
`}
|
|
</Markdown>
|
|
</>
|
|
),
|
|
},
|
|
]
|
|
}
|
|
|
|
export const OpenAIAgentsInstallation = createInstallation(getOpenAIAgentsSteps)
|