SDK Use Cases

The SDK is not just a base-URL swap. It gives you an application-level entry point for workflows that need traceability, controlled execution, and richer metadata than a plain provider call.

Use this page when you want to understand the kinds of products the SDK enables.

What you can build

User retention analytics

When you attach user and feature metadata to a trace, every AI request becomes easier to measure. That helps you answer questions like:

• which product surfaces are actually being used
• where users are getting blocked
• which cohorts create the most AI spend
• which workflows deserve more investment

const trace = await client.traces.create({
  metadata: {
    userId,
    orgId,
    feature: "sales_assistant",
    intent: "email_draft",
  },
});

const result = await client.execute({
  traceId: trace.data.id,
  input: "Draft a follow-up email for this deal.",
});

trace = client.traces.create(
    metadata={
        "user_id": user_id,
        "org_id": org_id,
        "feature": "sales_assistant",
        "intent": "email_draft",
    }
)

result = client.execute(
    trace_id=trace.id,
    input="Draft a follow-up email for this deal.",
)

trace = client.traces.create(
  metadata: {
    user_id: user_id,
    org_id: org_id,
    feature: "sales_assistant",
    intent: "email_draft",
  }
)

result = client.execute(
  trace_id: trace.id,
  input: "Draft a follow-up email for this deal."
)

The trace now carries the product context you need for analytics, replay, and cost attribution.

MCP-powered support workflows

Use the SDK when a support or operations workflow needs to call internal systems and still stay inside one governed trace.

Typical patterns:

• customer support assistants that query internal docs or tickets
• billing or account workflows that need scoped tool access
• incident helpers that fetch deployment or monitoring context

The SDK gives you a place to declare MCP tools, execute them through the application, and continue the same trace after tool results return.

Multi-step product automation

Some workflows are not one prompt and one response. They need several execute calls, usually with the same trace, so the full chain is visible later.

That is the right fit for:

• research assistants
• extraction pipelines
• review and approval workflows
• any task that benefits from explicit step history

Private and internal deployments

If your environment needs an outbound-only path, the SDK can point at the Olyx Agent rather than the hosted gateway.

That is useful when you need:

• internal provider access
• private MCP servers
• controlled egress
• a deployment model that works inside your own network boundary

Model comparison

Use runs.create when you want to compare models on the same input without changing your routing policy. That is helpful for:

• model selection reviews
• A/B comparisons
• regression checks after routing changes
• migration experiments

Safety and preview flows

Use simulate when you want to preview the path before you spend tokens or hit a provider.

That makes the SDK useful for:

• checking whether a request will be blocked
• previewing routing decisions
• estimating cost before execution
• validating policy and guardrail behaviour in a safer way