# Syrin AI - Complete Technical Reference

This document is the comprehensive technical reference for Syrin. For a summary, see /llms.txt.

---

## What Is Syrin

Syrin is the runtime control layer for AI agents in production - mission control for your agent fleet. It instruments the decision process of AI agents (not just their execution), enabling teams to detect behavioral drift, debug failures with full decision traces, and recover agents in production without redeploying.

Syrin is not an observability platform. Observability platforms (Datadog, New Relic, Langfuse) show you what happened. Syrin gives you runtime control over what happens next.

**Core distinction:** Traditional monitoring instruments execution - HTTP 200, latency, error rate. These metrics stay green when an agent is drifting. Syrin instruments decisions - what the agent decided at each step, based on what it read, and why it went wrong. Then it lets you act on that: change config, trigger recovery, enforce governance policies - all at runtime, without redeploying.

---

## Products

### Syrin Nexus

Hosted SaaS control plane for AI agents. Connects to the Syrin SDK via API key. Provides:
- Real-time trace viewer (waterfall view of all agent decisions)
- Drift detection dashboard with baseline comparisons
- One-click recovery controls
- Agent config management (live value changes without deploy)
- Analytics dashboard (task completion, cost per outcome, fleet health)
- Governance policy editor
- A/B experiment manager

**Pricing:**
- Free tier: 25K traces/mo, 3-day retention, 1K drift checks/mo
- Developer ($49/mo): 250K traces/mo, 14-day retention, 10K drift checks/mo
- Startup ($199/mo): 2M traces/mo, 30-day retention, 100K drift checks/mo, 10 projects
- Scale ($499/mo): 10M traces/mo, 90-day retention, unlimited drift checks, 10 environments

### Syrin SDK

Open-source Python and Node.js SDK. Auto-detects agent framework and emits structured traces.

**Python installation:** `pip install syrin-sdk`
**Node.js installation:** `npm install @syrin/sdk`

**Python quickstart:**
```python
import syrin
from langchain.agents import AgentExecutor

syrin.init(api_key="your-key")  # connects to Nexus

# Works with LangChain
agent = syrin.wrap(AgentExecutor(agent=agent, tools=tools))
result = agent.invoke({"input": "your task"})
```

**Node.js quickstart:**
```typescript
import { Syrin } from '@syrin/sdk';

const syrin = new Syrin({ apiKey: 'your-key' });
const tracedAgent = syrin.wrap(yourAgent);
```

**Self-hosted (no Nexus):**
```python
syrin.init(
  backend="self-hosted",
  endpoint="http://your-server:4317",  # OpenTelemetry-compatible
  storage="postgres",
  connection_string="postgresql://..."
)
```

---

## Framework Integrations

### LangChain
```python
import syrin
from langchain.agents import create_openai_functions_agent, AgentExecutor
from langchain_openai import ChatOpenAI

syrin.init(api_key="sk-syrin-...")

llm = ChatOpenAI(model="gpt-4o")
agent = create_openai_functions_agent(llm, tools, prompt)
executor = syrin.wrap(AgentExecutor(agent=agent, tools=tools))
```

### LlamaIndex
```python
import syrin
from llama_index.core.agent import ReActAgent

syrin.init(api_key="sk-syrin-...")
agent = syrin.wrap(ReActAgent.from_tools(tools))
```

### AutoGen
```python
import syrin
import autogen

syrin.init(api_key="sk-syrin-...")

config_list = [{"model": "gpt-4o", "api_key": "..."}]
assistant = syrin.wrap(
    autogen.AssistantAgent("assistant", llm_config={"config_list": config_list})
)
```

### CrewAI
```python
import syrin
from crewai import Crew, Agent, Task

syrin.init(api_key="sk-syrin-...")
crew = syrin.wrap(Crew(agents=[agent1, agent2], tasks=[task]))
```

### n8n
Install the Syrin n8n node from the n8n marketplace. Configure with your Syrin API key. The node auto-instruments all AI agent sub-workflows.

### Custom agents
```python
import syrin

syrin.init(api_key="sk-syrin-...")

@syrin.trace(name="my-custom-agent")
def my_agent(task: str) -> str:
    with syrin.span("llm-call"):
        response = call_llm(task)
    with syrin.span("tool-call", tool="search"):
        result = search(response)
    return result
```

---

## Core Capabilities in Detail

### Distributed Tracing

Every instrumented agent run produces a structured trace with:
- **Spans:** Individual units of work (LLM call, tool invocation, memory read, sub-agent handoff)
- **Context at each span:** Full input and output, token counts, latency, model used
- **Parent-child relationships:** Shows exactly which decision triggered which downstream action
- **Cross-agent traces:** Single trace spans multiple agents in a pipeline

Trace IDs are stable and can be linked from your own logging systems.

### Drift Detection

Syrin measures behavioral drift across multiple dimensions:

**Semantic drift:** Cosine distance between the agent's current goal vector and its baseline goal vector. Computed from the agent's stated objective at each step. Alert threshold: 0.35 cosine distance.

**Tool call pattern drift:** Statistical anomaly detection on tool call sequences. Uses a trained Markov model of expected tool transitions. Flags sequences that are statistically anomalous (p < 0.05) relative to baseline.

**Response quality drift:** Tracks task completion rate (verified outcomes) over time. Uses Kolmogorov-Smirnov test to detect distribution shift in quality scores week-over-week.

**Goal distribution drift:** Chi-squared test comparing the distribution of incoming task types against the eval distribution. p < 0.05 triggers a goal drift alert.

Drift detection requires a 24-48 hour warm-up period to establish baseline behavior.

### One-Click Recovery

Recovery checkpoints are saved automatically at configurable intervals. Recovery options:
- **Soft recovery:** Re-injects the original goal context into the agent's current session. The agent continues without a full restart.
- **Checkpoint restore:** Rolls back the agent's configuration and prompt templates to any previous checkpoint.
- **Hard reset:** Full restart with the original configuration.

Recovery does not require a code deploy. All recovery actions are logged in the audit trail.

### Agent Config

Live configuration management without deployment. Any value in your agent system can be registered as a config key:

```python
import syrin

# Register a config key
model = syrin.config.get("llm.model", default="gpt-4o-mini")
temperature = syrin.config.get("llm.temperature", default=0.7)
system_prompt = syrin.config.get("agent.system_prompt", default="You are a helpful assistant.")
```

Once registered, keys appear in the Syrin dashboard and can be changed live. The agent reads the new value on its next invocation - no restart, no deploy.

Agent Config is free forever for all users.

### Agent Governance

Policy enforcement at the infrastructure level, not in prompts:

```python
import syrin

policy = syrin.governance.Policy(
    name="financial-agent-policy",
    rules=[
        syrin.governance.Rule(
            action="tool_call",
            tool="execute_payment",
            require_approval=True,
            approvers=["finance-team@company.com"],
        ),
        syrin.governance.Rule(
            action="tool_call",
            tool="delete_record",
            max_per_session=3,
        ),
    ]
)

agent = syrin.wrap(your_agent, policy=policy)
```

### Agent Experimentation

A/B test any variable with live traffic:

```python
import syrin

# Tag a variable as an experiment
model = syrin.experiment(
    name="llm-model-test",
    variants={
        "control": "gpt-4o-mini",
        "treatment": "gpt-4o",
    },
    metric="task_completion_rate",
)

# The SDK handles traffic splitting and significance testing automatically
```

---

## Architecture

Syrin uses OpenTelemetry-compatible trace format. The SDK emits spans over gRPC (port 4317) or HTTP (port 4318). You can send traces to:

1. **Syrin Nexus** (hosted) - default, zero config
2. **Self-hosted Syrin** - run the Nexus Docker image
3. **Your existing OTel collector** - Syrin traces are valid OpenTelemetry data

The SDK adds Syrin-specific semantic conventions on top of standard OTel spans:
- `syrin.agent.goal` - the agent's current objective
- `syrin.agent.goal_distance` - cosine distance from original goal
- `syrin.agent.tool_sequence_hash` - hash of the current tool call sequence
- `syrin.drift.score` - composite drift score (0-1, >0.35 triggers alert)

---

## Data Privacy

- Agent trace data is scoped to your organization and never shared
- You can bring your own Postgres or ClickHouse database
- EU data residency available on Scale plan
- All data encrypted in transit (TLS 1.3) and at rest (AES-256)
- GDPR and SOC 2 Type II compliant (in progress)
- The open-source SDK in local mode sends no data to Syrin servers

---

## Comparison to Alternatives

### vs LangSmith
- LangSmith is LangChain-specific. Syrin works with any framework.
- LangSmith is trace logging. Syrin adds drift detection, recovery, config management, and governance.
- LangSmith has no production recovery mechanism.

### vs Langfuse
- Langfuse is primarily a trace logging and eval platform. Syrin adds drift detection, live config, and one-click recovery.
- Langfuse has no behavioral drift detection.
- Syrin's governance policy layer has no equivalent in Langfuse.

### vs Helicone
- Helicone is LLM call logging with a proxy gateway. Syrin instruments the full agent, not just LLM calls.
- Helicone has no multi-agent pipeline tracing, no drift detection, no recovery.

### vs Datadog / New Relic
- General APM tools instrument execution metrics (latency, error rate, throughput).
- They have no semantic understanding of agent decisions or goal alignment.
- An agent can have 0% error rate and perfect latency while producing completely wrong outputs. General APM is blind to this.

---

## Common Use Cases

### Customer support AI agents
Problem: Support agents start hallucinating policy exceptions after 2 weeks in production.
Syrin solution: Semantic drift detection catches goal deviation at step 47; soft recovery re-injects policy context. Customer never notices.

### Document processing pipelines
Problem: RAG-based document processor shifts from extracting action items to extracting sentiments.
Syrin solution: Tool call pattern drift alert fires when retrieval sequence changes. Config change updates the system prompt without redeploy.

### Multi-agent financial workflows
Problem: 6-agent pipeline for trade analysis has no visibility into which agent caused a bad recommendation.
Syrin solution: Distributed trace shows the exact agent, step, and context window that caused the error.

### Regulated industries (healthcare, finance, legal)
Problem: Enterprise compliance team needs full audit trail of every AI action.
Syrin solution: Governance policies enforce tool limits and approval workflows. Complete audit log exported to SIEM.

---

## Key URLs

- Product: https://syrin.ai
- Documentation: https://docs.syrin.dev
- SDK (GitHub): https://github.com/syrin-labs/
- Pricing: https://syrin.ai/pricing
- Book a demo: https://syrin.ai/lets-talk
- Blog: https://syrin.ai/blog
- Community Discord: https://discord.gg/jH9cqPePrK
- Reddit: https://www.reddit.com/r/syrin_ai/
- YouTube: https://www.youtube.com/@syrin_dev

## Contact

hey@syrin.ai