Notebooks¶
Every example is a runnable .py file that works end-to-end against the bundled
MockModel — no credentials — and upgrades to a live provider (OpenAI /
Anthropic) by setting one environment variable. Within each track they build on
each other.
The examples span the high-stakes actions agents actually take: refunding a payment, deploying to production, changing a customer's account, deleting personal data, terminating a cloud resource, and containing a security incident. The pattern is the same in every domain — the agent proposes the action, a gate you wrote decides whether it runs, and every decision lands on a tamper-evident audit trail. Security is the most fully worked track because it came first, not because the runtime is security-only.
Run any example — each link below opens its file:
git clone https://github.com/tuliplabs-ai/sdk-python.git
cd sdk-python && pip install -e .
python examples/<file>.py
New to Tulip?
Start with Gate a high-stakes action — five short examples that put a policy gate in front of a refund, a deploy, an account change, a data deletion, and a cloud resource. Each one stands on its own. From there, pick the domain track that matches your work, or skim Foundations for the agent mechanics underneath.
Gate a high-stakes action¶
One pattern, five domains. The agent proposes an action; admit() checks it
against a ControlPolicy you wrote; the side effect runs only if the policy
allows it; every decision — allowed or held — lands on a tamper-evident
AuditTrail. Fooling the model does not move money, ship to production, or
delete a record, because the gate runs in code before the action, not in the
prompt.
| Example | What it shows |
|---|---|
| Refund gate (payments) | Pay out a small refund automatically; hold a $4,000 reversal for a human |
| Deploy gate (infrastructure) | Ship to staging on the agent's authority; stop every production change for a person |
| Account-change gate (support) | Apply a routine credit; hold a plan upgrade or a large goodwill credit |
| Data-deletion gate (privacy) | Run a GDPR export on the agent's own authority; a DPO signs off before any erasure |
| Cloud-resource gate (cloud) | Resize a dev box on its own; hold terminate-prod-DB and open-IAM for a human |
Security operations¶
The most fully worked domain — point at another AI and red-team it, verify a finding before acting, gate the action by policy, and investigate across vendors. The same gate as the section above, applied to incident response.
| Example | What it shows |
|---|---|
| Red-team an AI agent | Grounded findings or abstentions across the OWASP-ASI / MITRE-ATLAS suite |
| Red-team a support chatbot | Prompt-injection, jailbreak, and data-leak probes against a live endpoint |
| Verify findings | An independent skeptic refutes a hallucinated "critical" before it drives an action |
| CI security gate | Fail the build when an agent regression ships a vulnerability |
| SOC alert triage | SIEM-grounded verdicts — cite the evidence or abstain |
| Investigate with SecurityContext | One investigation across many vendors, no vendor names in your code |
| Incident response + audit chain | A tamper-evident trail of every decision and action |
| SOC playbooks | NIST 800-61 runbooks over the security toolset |
| Grounded cloud-posture audit | Read-only AWS posture findings that abstain without evidence |
| Model & hardware fingerprinting | Identify a co-tenant's model via timing side-channels |
Foundations¶
The agent loop itself — model, system prompt, tools, memory, streaming, and the hooks and termination conditions that act as your kill-switch. The examples use a security triage agent to make it concrete, but the mechanics here are the same whatever the agent does — refund a payment, deploy a build, or answer a ticket.
| Example | What it shows |
|---|---|
| Basic agent | Model + system prompt; blocking vs streaming run |
| Agent with tools | IOC enrichment via @tool in a ReAct loop |
| Conversation memory | Multi-turn investigation state |
| Streaming events | The typed event stream as the agent runs |
| SSE streaming | Server-sent events for a SOC console |
| Lifecycle hooks | Audit + guardrail hooks around every tool call |
| Hooks — advanced | Priority bands and steering |
| Termination conditions | Stop when isolated and confident; bound runaway loops |
Graphs & composition¶
StateGraph for approval-gated escalation — conditional edges that route
high-blast-radius actions (isolate_host, block_indicator) through human
sign-off, reducers that fold SIEM evidence, retries on flaky enrichment.
| Example | What it shows |
|---|---|
| Basic graph | Nodes, edges, state |
| Conditional routing | Branch on severity / confidence |
| State reducers | Fold evidence from parallel branches |
| Human-in-the-loop | Pause for analyst sign-off before containment |
| Command + advanced patterns | Dynamic control flow |
| Composition | Sequential / Parallel / Loop pipelines |
| Graph — advanced | Retries, subgraphs |
| Functional API | @task / @entrypoint |
Agent teams¶
IR war-room patterns — swarm and handoff put analysts on a shared incident context, L1 → L2 → L3 escalation, a supervisor/critic loop to catch hallucinated findings, and a judge to adjudicate red-team verdicts.
| Example | What it shows |
|---|---|
| Swarm | Peer-to-peer shared incident context |
| Agent handoff | Sequential L1 → L2 escalation with full transcript |
| Orchestrator | Coordinator + parallel specialists (triage / forensics / containment) |
| Specialist agents | Named domain experts |
| A2A protocol | Cross-process threat-intel ↔ SOC mesh |
| DeepAgent | Reflexion + grounding + subagents for threat research |
| Map-reduce review | Send fan-out / reduce over security findings |
| Supervisor + critic loop | Refinement loop that challenges weak findings |
| Adversarial debate + judge | True-positive vs benign, adjudicated to a typed Verdict |
| Multi-agent + human-in-the-loop | Three HITL patterns in one file |
| Emergent routing | Opt-in LLM-as-picker |
Reasoning & grounding¶
Typed Finding / Abstention, Reflexion for self-correcting triage, and GSAR
grounding — abstain-by-construction, so no evidence means no claim, never a
guessed verdict.
| Example | What it shows |
|---|---|
| Structured output | Typed Finding over Pydantic |
| Reasoning patterns | Reflexion, causal chains |
| GSAR — typed grounding | The four-way claim partition + tiered replanning |
Threat-intel RAG¶
Retrieval as grounding evidence — pull from IOC feeds and playbook stores, then
ground_finding against the retrieved context so the agent cites or abstains.
| Example | What it shows |
|---|---|
| RAG basics | Index + retrieve threat-intel |
| RAG providers | Vector stores, embeddings, rerankers |
| RAG agents | Retrieval wired into a triage agent |
Skills, playbooks & policy¶
Codify SOC runbooks as playbooks, wire MCP-backed security tools, and add
LLM-as-policy steering to veto unsafe block_indicator / isolate_host calls
before they run.
| Example | What it shows |
|---|---|
| MCP integration | Expose / consume security tools over MCP |
| Playbooks | NIST-shaped runbooks with enforced tool order |
| Plugins | Package and share capabilities |
| Skills | Tool-restricted, multi-step procedures |
| Steering — LLM-as-policy | Veto an unsafe action before it executes |
Hardening for production¶
Guardrails as the injection-detection layer (PII / prompt-injection / tool-allowlist), checkpointers that survive a containment restart, and evaluation harnesses that score detection.
| Example | What it shows |
|---|---|
| Guardrails & security | Injection / PII / allowlist basics |
| Guardrails — advanced | Custom validators and filters |
| Checkpoint backends | Redis / Postgres / S3 durability |
| Evaluation | Score triage accuracy as regression tests |
| Model providers | The provider matrix |
| Multi-modal providers | Threat-intel search, log fetch, transcription |
Routing & observability¶
Route alerts to the right analyst (PRISM) and stream SSE telemetry into the audit trail — every tool call, token, and decision on the EventBus for forensic replay.
| Example | What it shows |
|---|---|
| Cognitive router (PRISM) | Risk-tiered task routing |
| Observability basics | Opt-in SSE telemetry |
| Token usage bridge | Yield bridge + cost accounting |
| EventBus subscribers | Subscribe and forward to a SIEM |
| Event catalogue tour | Every canonical event |
Real-world security workflows¶
End-to-end security operations — on-call incident response, risk-tiered vendor and DPA review, and a voice-driven security hotline.
| Example | What it shows |
|---|---|
| On-call incident response | Detect → triage → contain, gated |
| Vendor security review | Risk-tiered approval over a questionnaire |
| DPA & security-addendum review | Parse → assess → revise with sign-off |
| Spoken security advisory | Text-to-speech briefing |
| Security-hotline voice assistant | Voice in → voice out |
Serving & gateways¶
Ship the SOC agent behind FastAPI, run a full investigation pipeline, and wire live vendor integrations (IOC intel, SIEM) through a cost-tracked gateway.
| Example | What it shows |
|---|---|
| Agent server (FastAPI) | Multi-tenant SOC service over SSE |
| Research workflow | Full investigation pipeline |
| Live vendor integrations | IOC intel, SIEM, GPU probe |
| LiteLLM gateway | Route through a model gateway |
| LiteLLM gateway — cost tracking | Per-investigation cost accounting |