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, resizing a cloud fleet. 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. The tracks below work through payments, customer support, infrastructure, and privacy scenarios; one dedicated track applies the same gate to security operations.
Run any example — each link below opens its file:
git clone https://github.com/tuliplabs-ai/tulip-agents.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 |
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 run on everyday operations — payments triage, a deployment-readiness check, a support conversation, a GDPR request stream, a deploy-change gate — but the mechanics are the same whatever the agent does.
| Example | What it shows |
|---|---|
| Basic agent | Model + system prompt; blocking vs streaming run |
| Agent with tools | A deployment-readiness check via @tool in a ReAct loop |
| Conversation memory | A support conversation persisted to Redis and resumed |
| Streaming events | The typed event stream as the agent runs |
| SSE streaming | Server-sent events for a payments-operations dashboard |
| Lifecycle hooks | Audit + guardrail hooks around every tool call |
| Hooks — advanced | Cancel or retry mid-flight — a change gate for a deploy agent |
| Termination conditions | Stop when the ticket is resolved; bound runaway loops |
Graphs & composition¶
StateGraph and the composition pipelines for multi-step work — conditional
edges that route a cloud alert by severity, reducers that fold parallel payment
checks into one authorization state, an approval interrupt before any
production change, and per-node retries for a flaky provisioning control plane.
| Example | What it shows |
|---|---|
| Basic graph | Nodes, edges, state |
| Conditional routing | Branch on severity; an LLM as the router |
| State reducers | Fold parallel payment checks into one state |
| Human-in-the-loop | Pause for human sign-off before a production change |
| Command + advanced patterns | Dynamic control flow |
| Composition | Sequential / Parallel / Loop pipelines |
| Graph — advanced | Per-node retries and caching; graph diagrams |
| Functional API | @task / @entrypoint |
Agent teams¶
Patterns for more than one agent — a swarm working an outage war room, L1 → L2 → L3 support escalation with typed handoffs, an orchestrator routing a data-subject request to specialists, a supervisor/critic loop that grounds a report before it ships, and a judge that adjudicates an incident-vs-noise debate.
| Example | What it shows |
|---|---|
| Swarm | Peer-to-peer shared incident context |
| Agent handoff | Sequential L1 → L2 escalation with full transcript |
| Orchestrator | A privacy officer routes a request to parallel specialists |
| Specialist agents | Named domain experts |
| A2A protocol | Cross-process A2A — a payment-risk agent a partner bank can call |
| DeepAgent | Reflexion + grounding + subagents for a fleet reliability review |
| Map-reduce review | Send fan-out / reduce over support tickets |
| Supervisor + critic loop | Refinement loop that grounds a report before it ships |
| Adversarial debate + judge | Incident vs noise, adjudicated to a typed Verdict |
| Multi-agent + human-in-the-loop | Three HITL patterns in one file |
Reasoning & grounding¶
Typed structured output, Reflexion self-critique, and GSAR grounding — abstain-by-construction, so no evidence means no claim, never a guessed conclusion.
| Example | What it shows |
|---|---|
| Structured output | A typed ticket update on result.parsed |
| Reasoning patterns | Reflexion, causal chains |
| GSAR — typed grounding | The four-way claim partition + tiered replanning |
RAG & retrieval¶
Retrieval as grounding evidence — index a cloud best-practice catalogue, choose embedding and vector-store providers over a payments runbook, then wire retrieval into an on-call copilot so its advice cites your runbooks instead of model memory.
| Example | What it shows |
|---|---|
| RAG basics | Index + retrieve a cloud best-practice catalogue |
| RAG providers | Swappable vector stores and embeddings |
| RAG agents | Retrieval as a tool in an on-call SRE copilot |
Skills, playbooks & policy¶
Codify procedure — GDPR data-subject-request playbooks with enforced tool order, vetted payments-ops skills with progressive disclosure, support-desk systems wired in over MCP, and LLM-as-policy steering that vetoes a mutating infra call before it runs.
| Example | What it shows |
|---|---|
| MCP integration | Expose / consume support-desk tools over MCP |
| Playbooks | GDPR request procedures 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 over input and output (PII, prompt-injection patterns, tool allowlists), checkpointers that let a support case survive a restart, and an evaluation harness that pins agent behaviour as regression tests.
| Example | What it shows |
|---|---|
| Guardrails & security | Injection / PII / allowlist basics |
| Guardrails — advanced | Topic, content, and output-filter policies |
| Checkpoint backends | S3-backed durability; SQL and Redis via the same contract |
| Evaluation | Score a data-access reviewer as regression tests |
| Model providers | The provider matrix |
| Multi-modal providers | Chargeback evidence: web fetch, ledger search, image, transcription |
Observability¶
Put every tool call, token, and decision on the EventBus — a replayable ticket timeline, a telemetry forwarder that spans concurrent rollouts, and an event catalogue generated from the code.
| Example | What it shows |
|---|---|
| Observability basics | Opt-in EventBus telemetry |
| Token usage bridge | Yield bridge + cost accounting |
| EventBus subscribers | Subscribe shapes; forward rollout telemetry |
| Event catalogue tour | Every canonical event |
Real-world workflows¶
End-to-end operations — on-call incident response for an SRE team, risk-tiered support-concession and vendor-DPA approvals, and voice in / voice out for a payments support line.
| Example | What it shows |
|---|---|
| On-call incident response | Triage → investigate → mitigate, gated |
| Support concession approval | Risk-tiered approval chain for costly concessions |
| Vendor DPA & data-privacy review | Parse → assess → revise with sign-off |
| Spoken cloud status advisory | Text-to-speech briefing |
| Payments support voice line | Voice in → voice out |
Serving & gateways¶
Ship an agent behind FastAPI, run a research pipeline over a support knowledge base, wire live vendor integrations for privacy work, and route every model call through a cost-tracked gateway.
| Example | What it shows |
|---|---|
| Agent server (FastAPI) | An on-call triage copilot over SSE, key-scoped threads |
| Research workflow | A support analyst works a known-issue KB end-to-end |
| Live vendor integrations | PII discovery, data map, scan dispatch |
| LiteLLM gateway | Route through a model gateway |
| LiteLLM gateway — cost tracking | Per-team cost tracking and budgets |
Security operations¶
The most fully worked domain track — point a red-team suite at another AI, verify a finding before acting on it, gate the containment action by policy, and investigate across vendors. The same gate as the tracks 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 |