Skip to content

Commit 905e83b

Browse files
namrataghadi-galileojoaomdmouraclaude
authored
feat(examples): Feat/crewai examples expansion port (#142)
Cherry Pick CrewAI examples --------- Co-authored-by: Joao Moura <joaomdmoura@gmail.com> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
1 parent da05f98 commit 905e83b

55 files changed

Lines changed: 5014 additions & 965 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎examples/crewai/README.md‎

Lines changed: 232 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,242 @@
1-
# CrewAI Example
1+
# CrewAI + Agent Control Examples
22

3-
Combine Agent Control security controls with CrewAI guardrails for customer support workflows.
3+
Combines **Agent Control** (runtime security & compliance) with **CrewAI** (agent orchestration) for production-grade AI agents.
44

5-
## What this example shows
5+
**Agent Control** enforces guardrails at tool boundaries -- blocking unauthorized access, PII leakage, SQL injection, and more -- while **CrewAI Guardrails** handle quality retries. Both coexist without code changes to CrewAI.
66

7-
- Pre/post controls for access and PII protection
8-
- CrewAI guardrails for quality retries
9-
- Multi-layer control enforcement
7+
## How It Works
108

11-
## Quick run
9+
```
10+
User Request
11+
|
12+
v
13+
CrewAI Agent (planning & orchestration)
14+
|
15+
v
16+
@control() decorator (PRE check) <- LAYER 1: Agent Control validates input
17+
|
18+
v
19+
Tool executes (LLM call, DB query, etc.)
20+
|
21+
v
22+
@control() decorator (POST check) <- LAYER 2: Agent Control validates output
23+
|
24+
v
25+
CrewAI Guardrails (quality retries) <- LAYER 3: CrewAI validates quality
26+
|
27+
v
28+
Return to user (or block / steer / warn)
29+
```
30+
31+
**Agent Control** blocks or steers immediately (security). **CrewAI Guardrails** retry with feedback (quality). Controls are defined on the **server** -- update rules without redeploying agents.
32+
33+
## Prerequisites
34+
35+
- **Python 3.12+**
36+
- **uv** -- Fast Python package manager (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
37+
- **Docker** -- For PostgreSQL (`docker compose -f docker-compose.dev.yml up -d`)
38+
- **OpenAI API key** -- `export OPENAI_API_KEY="your-key"` (only needed for full LLM crew runs; simulated scenarios work without it)
39+
40+
## Quick Start
41+
42+
### 1. Install dependencies
43+
44+
From the monorepo root:
45+
46+
```bash
47+
cd /path/to/agent-control
48+
make sync
49+
```
50+
51+
### 2. Start the Agent Control server
52+
53+
In a separate terminal:
1254

1355
```bash
14-
# From repo root
1556
make server-run
16-
export OPENAI_API_KEY="your-key-here"
57+
```
58+
59+
Verify it's running:
60+
61+
```bash
62+
curl http://localhost:8000/health
63+
# {"status":"healthy","version":"0.1.0"}
64+
```
65+
66+
### 3. Pick an example and run it
67+
68+
Each example has a `setup_controls.py` (one-time, idempotent) and a main script:
1769

18-
# In a separate shell
19-
cd examples/crewai
20-
uv pip install -e . --upgrade
21-
uv run python setup_content_controls.py
22-
uv run python content_agent_protection.py
70+
```bash
71+
cd examples/crewai/secure_research_crew
72+
uv run --active python setup_controls.py
73+
uv run --active python -m secure_research_crew.main
2374
```
2475

25-
Full walkthrough: https://docs.agentcontrol.dev/examples/crewai
76+
---
77+
78+
## Examples
79+
80+
### 1. [Steering Financial Agent](./steering_financial_agent/) -- Deny, Steer & Warn
81+
82+
Demonstrates all three Agent Control action types in a wire-transfer scenario:
83+
84+
| Action | Behavior | Example |
85+
|--------|----------|---------|
86+
| **DENY** | Hard block, no recovery | Sanctioned country, fraud detected |
87+
| **STEER** | Pause, guide agent to correct, retry | 2FA required, manager approval needed |
88+
| **WARN** | Log for audit, no blocking | New recipient, unusual activity |
89+
90+
```bash
91+
cd examples/crewai/steering_financial_agent
92+
uv run --active python setup_controls.py
93+
uv run --active python -m steering_financial_agent.main
94+
```
95+
96+
### 2. [Evaluator Showcase](./evaluator_showcase/) -- All 4 Built-in Evaluators
97+
98+
Demonstrates every built-in evaluator in a data-analyst scenario:
99+
100+
| Evaluator | Stage | Purpose |
101+
|-----------|-------|---------|
102+
| **SQL** | PRE | Block DROP/DELETE, enforce LIMIT, prevent injection |
103+
| **LIST** | PRE | Restrict access to sensitive tables |
104+
| **REGEX** | POST | Catch SSN, email, credit cards in query results |
105+
| **JSON** | PRE | Validate required fields, enforce constraints, steer for missing data |
106+
107+
```bash
108+
cd examples/crewai/evaluator_showcase
109+
uv run --active python setup_controls.py
110+
uv run --active python -m evaluator_showcase.main
111+
```
112+
113+
### 3. [Secure Research Crew](./secure_research_crew/) -- Multi-Agent Crew with Per-Role Policies
114+
115+
A production-quality **3-agent sequential crew** (Researcher, Analyst, Writer) where each agent has its own policy with distinct controls. This is the pattern you'd use in real multi-agent systems.
116+
117+
```
118+
+--------------+ +--------------+ +---------------+
119+
| Researcher | --> | Analyst | --> | Writer |
120+
| | | | | |
121+
| query_database| | validate_data| | write_report |
122+
+--------------+ +--------------+ +---------------+
123+
| | |
124+
data-access-policy analysis-validation content-safety
125+
- SQL safety [deny] - Required fields [deny] - PII blocker [deny]
126+
- Restricted tables - Methodology [steer]
127+
[deny]
128+
```
129+
130+
**5 scenarios** -- all run without LLM calls (direct tool testing):
131+
132+
| # | Scenario | Agent | Evaluator | Action | Result |
133+
|---|----------|-------|-----------|--------|--------|
134+
| 1 | Happy path | All 3 | All | allow | Report generated with sources |
135+
| 2 | SQL injection | Researcher | SQL | deny | "Multiple SQL statements not allowed" |
136+
| 3 | Restricted table | Researcher | LIST | deny | salary_data access blocked |
137+
| 4 | Missing methodology | Analyst | JSON Schema | steer | Auto-corrected, passes on retry |
138+
| 5 | PII in report | Writer | REGEX | deny | SSN/email/phone blocked |
139+
140+
```bash
141+
cd examples/crewai/secure_research_crew
142+
uv run --active python setup_controls.py
143+
uv run --active python -m secure_research_crew.main
144+
```
145+
146+
### 4. [Content Publishing Flow](./content_publishing_flow/) -- CrewAI Flow with Routing & Human-in-the-Loop
147+
148+
A complete **CrewAI Flow** using `@start`, `@listen`, and `@router` decorators with Agent Control guardrails at every pipeline stage. Content is routed through different paths based on risk level, with embedded crews and steering for human approval.
149+
150+
```
151+
@start: intake_request (JSON validation)
152+
|
153+
@listen: research (Researcher + Fact-Checker)
154+
|
155+
@listen: draft_content (PII + banned topic checks)
156+
|
157+
@router: quality_gate
158+
|
159+
+-- "low_risk" (blog_post) --> auto_publish (final PII scan)
160+
+-- "high_risk" (press_release) --> compliance_review (legal + editor steering)
161+
+-- "escalation" (internal_memo)--> human_review (STEER: manager approval)
162+
```
163+
164+
**6 scenarios** covering all three routing paths plus control blocking:
165+
166+
| # | Scenario | Flow Path | Result |
167+
|---|----------|-----------|--------|
168+
| 1 | Blog post | low_risk -> auto-publish | Published |
169+
| 2 | Press release | high_risk -> compliance review | Steered (exec summary), then published |
170+
| 3 | Internal memo | escalation -> human review | Steered: pending manager approval |
171+
| 4 | Invalid request | intake blocked | JSON evaluator: missing fields |
172+
| 5 | Banned topic | draft blocked | LIST evaluator: "insider trading" detected |
173+
| 6 | PII in draft | draft blocked | REGEX evaluator: email/SSN/phone detected |
174+
175+
```bash
176+
cd examples/crewai/content_publishing_flow
177+
uv run --active python setup_controls.py
178+
uv run --active python -m content_publishing_flow.main
179+
```
180+
181+
---
182+
183+
## Feature Coverage
184+
185+
| Feature | Ex 1 | Ex 2 | Ex 3 | Ex 4 |
186+
|---------|:----:|:----:|:----:|:----:|
187+
| `@control()` decorator | Yes | Yes | Yes | Yes |
188+
| PRE-execution checks | Yes | Yes | Yes | Yes |
189+
| POST-execution checks | Yes | Yes | Yes | Yes |
190+
| **deny** action | Yes | Yes | Yes | Yes |
191+
| **steer** action | Yes | Yes | Yes | Yes |
192+
| **warn** action | Yes | | | |
193+
| Regex evaluator | | Yes | Yes | Yes |
194+
| List evaluator | Yes | Yes | Yes | Yes |
195+
| JSON evaluator | Yes | Yes | Yes | Yes |
196+
| SQL evaluator | | Yes | Yes | |
197+
| Steering context + retry loop | Yes | Yes | Yes | Yes |
198+
| ControlViolationError handling | Yes | Yes | Yes | Yes |
199+
| ControlSteerError handling | Yes | Yes | Yes | Yes |
200+
| **Multi-agent crew** | | | **Yes** | |
201+
| **Per-agent policies** | | | **Yes** | |
202+
| **CrewAI Flow (@start/@listen/@router)** | | | | **Yes** |
203+
| **Conditional routing** | | | | **Yes** |
204+
| **Human-in-the-loop (steer)** | | | | **Yes** |
205+
| **Pydantic state management** | | | | **Yes** |
206+
207+
## Architecture Deep Dive
208+
209+
### Multi-Agent Crew (Example 3)
210+
211+
The SDK supports one `agent_control.init()` per process. All three CrewAI agents share a single Agent Control identity, but each tool's `step_name` routes it to the right policy:
212+
213+
```
214+
Single agent_control.init()
215+
|
216+
+------------------------------------------------------------+
217+
| CrewAI Sequential Crew |
218+
| |
219+
| +--------------+ +--------------+ +----------------+ |
220+
| | Researcher |-->| Analyst |-->| Writer | |
221+
| | query_database| | validate_data| | write_report | |
222+
| +--------------+ +--------------+ +----------------+ |
223+
+------------------------------------------------------------+
224+
| | |
225+
data-access-policy analysis-validation content-safety
226+
(SQL + LIST deny) (JSON deny + steer) (REGEX deny)
227+
```
228+
229+
### CrewAI Flow (Example 4)
230+
231+
```
232+
@start: intake_request -----> @listen: research -----> @listen: draft_content
233+
(JSON validation) (LIST + REGEX checks) (REGEX + LIST checks)
234+
|
235+
@router: quality_gate
236+
/ | \
237+
/ | \
238+
"low_risk" "high_risk" "escalation"
239+
| | |
240+
auto_publish compliance human_review
241+
(REGEX PII) (JSON + STEER) (STEER)
242+
```

0 commit comments

Comments
 (0)