From 704466695e34d33bde9bcf8a8e1c2a5f480446f2 Mon Sep 17 00:00:00 2001 From: NagaSatish Date: Fri, 4 Sep 2026 14:49:33 +0530 Subject: [PATCH] docs: add TealTiger governance integration page TealTiger is an open-source deterministic AI governance layer. This page shows how to surface its decisions (action, risk score, reason codes) in Helicone by attaching them as custom properties via toHeliconeHeaders(), so governance status is visible and filterable per request in the dashboard. Adds docs/other-integrations/tealtiger.mdx and registers it under the Frameworks group in docs.json. --- docs/docs.json | 3 +- docs/other-integrations/tealtiger.mdx | 148 ++++++++++++++++++++++++++ 2 files changed, 150 insertions(+), 1 deletion(-) create mode 100644 docs/other-integrations/tealtiger.mdx diff --git a/docs/docs.json b/docs/docs.json index 2e7b990055..d8ab55a444 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -240,7 +240,8 @@ "getting-started/integration-method/crewai", "other-integrations/dify", "gateway/integrations/llamaindex", - "other-integrations/ragas" + "other-integrations/ragas", + "other-integrations/tealtiger" ] }, { diff --git a/docs/other-integrations/tealtiger.mdx b/docs/other-integrations/tealtiger.mdx new file mode 100644 index 0000000000..79531515d9 --- /dev/null +++ b/docs/other-integrations/tealtiger.mdx @@ -0,0 +1,148 @@ +--- +title: "TealTiger Integration" +sidebarTitle: "TealTiger" +description: "Surface deterministic AI governance decisions in Helicone by attaching TealTiger metadata as custom properties." +"twitter:title": "TealTiger Integration - Helicone OSS LLM Observability" +iconType: "solid" +--- + +[TealTiger](https://github.com/agentguard-ai/tealtiger) is an open-source +deterministic governance layer for AI agents: tool allowlists, PII and secret +detection, prompt-injection blocking, and cost limits, with no LLM in the +governance path. Each evaluation returns a `Decision` (action, risk score, +reason codes, correlation id). + +When you route LLM calls through Helicone, you can attach that decision as +Helicone [custom properties](/features/advanced-usage/custom-properties) so the +governance status of every request is visible and filterable in your Helicone +dashboard, with no extra instrumentation. + + + + Log into [Helicone](https://www.helicone.ai) or create an account. Then + generate an [API key](https://helicone.ai/developer). + + +```bash +npm install tealtiger openai +``` + +```bash +export HELICONE_API_KEY= +export OPENAI_API_KEY= +``` + + +```typescript +import { TealEngine, toHeliconeHeaders } from "tealtiger"; + +// Define a governance policy (here: only web_search is allowed). +const engine = new TealEngine({ + tools: { + web_search: { allowed: true }, + shell: { allowed: false }, + }, +}); + +// Evaluate the action the agent is about to take. +const decision = engine.evaluate({ + agentId: "research-agent-1", + action: "tool.execute", + tool: "web_search", +}); +``` + + + +`toHeliconeHeaders(decision)` maps the decision to `Helicone-Property-*` +headers. Spread them into your client's `defaultHeaders` alongside your +Helicone auth: + +```typescript +import OpenAI from "openai"; + +const client = new OpenAI({ + apiKey: process.env.OPENAI_API_KEY, + baseURL: "https://oai.helicone.ai/v1", + defaultHeaders: { + "Helicone-Auth": `Bearer ${process.env.HELICONE_API_KEY}`, + ...toHeliconeHeaders(decision), + }, +}); +``` + +This attaches the following custom properties to each request: + +| Property | Example value | +| --- | --- | +| `Helicone-Property-TealTiger-Action` | `ALLOW` / `DENY` / `REDACT` | +| `Helicone-Property-TealTiger-Risk-Score` | `0`–`100` | +| `Helicone-Property-TealTiger-Reason-Codes` | `PII_DETECTED,SECRET_DETECTED` | +| `Helicone-Property-TealTiger-Correlation-Id` | correlation id (join key to your audit trail) | + +Open the Helicone dashboard and filter the request table by the +`TealTiger-Action` property to see governance status per request. + + + + +## Complete working example + +```typescript +import OpenAI from "openai"; +import { TealEngine, toHeliconeHeaders } from "tealtiger"; + +const engine = new TealEngine({ + tools: { + web_search: { allowed: true }, + shell: { allowed: false }, + }, +}); + +async function main() { + const decision = engine.evaluate({ + agentId: "research-agent-1", + action: "tool.execute", + tool: "web_search", + }); + + const client = new OpenAI({ + apiKey: process.env.OPENAI_API_KEY, + baseURL: "https://oai.helicone.ai/v1", + defaultHeaders: { + "Helicone-Auth": `Bearer ${process.env.HELICONE_API_KEY}`, + ...toHeliconeHeaders(decision), + }, + }); + + const response = await client.chat.completions.create({ + model: "gpt-4o-mini", + messages: [ + { role: "user", content: "Summarize the benefits of deterministic AI governance." }, + ], + }); + + console.log(response.choices[0]?.message?.content); +} + +main(); +``` + + + In `ENFORCE` mode you would short-circuit on a `DENY` decision before calling + the model. Letting the call proceed (as above) records the governance + properties against a real request so they appear in Helicone. + + +## Options + +`toHeliconeHeaders(decision, options)` accepts options to include the policy +id/version, toggle the correlation and trace ids, or use a custom property +prefix. Use `withHeliconeHeaders(existingHeaders, decision)` to merge +governance properties into headers you already have. + +## Learn more + +- [TealTiger on GitHub](https://github.com/agentguard-ai/tealtiger) +- [TealTiger on npm](https://www.npmjs.com/package/tealtiger) +- [Helicone custom properties](/features/advanced-usage/custom-properties)