You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
feat(customer-onboarding): add --json output flag (#169) - #242
Adds an optional --json output flag to the customer-onboarding recipe, mirroring the structured Pydantic output pattern established in recipes/lead-qualification. When --json is supplied, the terminal task formats and emits pure machine-readable JSON matching the newly defined CustomerOnboardingResult Pydantic model (CustomerProfile + OnboardingEmail).
Defined CustomerProfile: Captures customer signup signals (customer_name, company, role, use_case, team_size), audit status ("READY" or "INCOMPLETE"), completeness_score ("High", "Medium", or "Low"), and missing_fields list.
Defined OnboardingEmail: Captures the tailored outbound message (subject, body).
Defined CustomerOnboardingResult: Root container holding profile and email.
Task & Crew Wiring (tasks.py, crew.py):
Threaded json_output: bool = False through build_crew(...) and build_tasks(...).
Wired output_pydantic=CustomerOnboardingResult if json_output else None to the terminal task (composer_task).
Dynamically adjusted expected_output and prompt guidelines on composer_task when structured output is requested.
Preserved default non-JSON behavior and full backward compatibility for programmatic callers (main.py, playground, tests).
CLI & Machine-Readable Output (run.py):
Added --json command-line flag (action="store_true").
In JSON mode, decorative terminal banners (🚀, ═) and logging are suppressed so stdout contains strictly valid JSON parseable by jq and python -c 'import sys, json; json.load(sys.stdin)'.
Implemented format_json_output(result) with type-safe isinstance checks supporting BaseModel, CrewOutput (.pydantic, .json_dict, .json, .raw), dictionary representations, and markdown code fence stripping.
Missing configuration (check_env) and runtime execution errors emit structured {"error": "<msg>"} to stdout and exit with code 1.
Testing (test_main.py):
Added 16 deterministic offline unit tests covering:
Default execution and backward compatibility.
Pydantic schema validation, serialization, and round-trip.
Includes zero-dependency offline mock fallback for crewai so tests run reliably both locally and in CI.
Known Limitations:
Real CrewAI live runtime execution was verified through the repository's test contract and AST validation suite with mocked LLM calls; live NVIDIA NIM calls were not executed to avoid live API token usage in automated testing.
Checklist
I ran my recipe end-to-end with deterministic offline mocks
ruff check and ruff format --check pass locally
I added/updated the recipe's README.md (inputs, outputs, sample run, and piping examples)
.env.example lists all required variables with placeholder values (no real keys)
This PR touches one recipe (recipes/customer-onboarding)
Sample output
1. JSON Mode (python run.py --json)
{
"profile": {
"customer_name": "Sarah Connor",
"company": "Cyberdyne Systems",
"role": "Chief Security Officer",
"use_case": "Automating threat intelligence aggregation and incident response",
"team_size": "50",
"status": "READY",
"completeness_score": "High",
"missing_fields": []
},
"email": {
"subject": "Welcome to Cyberdyne Systems — Let's Elevate Your Threat Intelligence",
"body": "Hi Sarah,\n\nWelcome aboard! We are thrilled to partner with Cyberdyne Systems as your team of 50 scales your threat intelligence aggregation and incident response workflows..."
}
}
🎉 Thanks for your first pull request to crewai-recipes! A maintainer will review it soon (usually within 7 days). Make sure CI is green and the PR checklist is filled in — that speeds up review a lot.
• Add an optional --json mode for downstream tools while preserving the existing email output.
• Define a structured onboarding result containing the audited profile and composed email.
• Document JSON usage and add offline tests for schema, CLI, and error behavior.
The following are alternative approaches to this PR:
1. Control workflow verbosity in JSON mode
➕ Protects parseable stdout from CrewAI execution traces, not just CLI banners.
➖ Requires mode-aware logging or verbosity across the crew and agents.
Recommendation: Keep the optional Pydantic output on the terminal task; it preserves the existing workflow. Before relying on the documented JSON-only stdout contract, disable or redirect CrewAI verbosity in JSON mode: the crew and agents are still configured with verbose=True, which the mocked CLI tests do not exercise.
Files changed (5) +611 / -46
Enhancement (3) +170 / -38
crew.pyPass JSON mode into task construction+3/-0
Pass JSON mode into task construction
• Adds an optional 'json_output' argument to 'build_crew' and forwards it to 'build_tasks', leaving existing callers on the default path.
run.pyAdd JSON CLI output and structured errors+114/-34
Add JSON CLI output and structured errors
• Adds '--json', result serialization across Pydantic and CrewOutput-like representations, and JSON errors for missing credentials or execution failures. The default banner-and-email presentation remains available.
• Introduces Pydantic models for the audited customer profile and onboarding email. JSON mode changes the terminal task's instructions and selects 'CustomerOnboardingResult' as its structured output.
test_main.pyCover schema, task wiring, and both CLI modes+390/-8
Cover schema, task wiring, and both CLI modes
• Expands offline tests for model round-trips, incomplete profiles, terminal-task wiring, JSON formatting, CLI output, and error paths. Adds a CrewAI mock fallback when the package is unavailable.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What does this PR do?
Adds an optional
--jsonoutput flag to thecustomer-onboardingrecipe, mirroring the structured Pydantic output pattern established inrecipes/lead-qualification. When--jsonis supplied, the terminal task formats and emits pure machine-readable JSON matching the newly definedCustomerOnboardingResultPydantic model (CustomerProfile+OnboardingEmail).Related issue
Closes #169
Type of change
Implementation & Architecture Details
Pydantic Models (
recipes/customer-onboarding/tasks.py):CustomerProfile: Captures customer signup signals (customer_name,company,role,use_case,team_size), auditstatus("READY"or"INCOMPLETE"),completeness_score("High","Medium", or"Low"), andmissing_fieldslist.OnboardingEmail: Captures the tailored outbound message (subject,body).CustomerOnboardingResult: Root container holdingprofileandemail.Task & Crew Wiring (
tasks.py,crew.py):json_output: bool = Falsethroughbuild_crew(...)andbuild_tasks(...).output_pydantic=CustomerOnboardingResult if json_output else Noneto the terminal task (composer_task).expected_outputand prompt guidelines oncomposer_taskwhen structured output is requested.main.py, playground, tests).CLI & Machine-Readable Output (
run.py):--jsoncommand-line flag (action="store_true").🚀,═) and logging are suppressed so stdout contains strictly valid JSON parseable byjqandpython -c 'import sys, json; json.load(sys.stdin)'.format_json_output(result)with type-safeisinstancechecks supportingBaseModel,CrewOutput(.pydantic,.json_dict,.json,.raw), dictionary representations, and markdown code fence stripping.check_env) and runtime execution errors emit structured{"error": "<msg>"}to stdout and exit with code 1.Testing (
test_main.py):status="INCOMPLETE",missing_fields).--jsonflag parsing and banner suppression.check_enverror emission in JSON and human modes.json.load(sys.stdin)pipeline compatibility.crewaiso tests run reliably both locally and in CI.Known Limitations:
Checklist
ruff checkandruff format --checkpass locallyREADME.md(inputs, outputs, sample run, and piping examples).env.examplelists all required variables with placeholder values (no real keys)recipes/customer-onboarding)Sample output
1. JSON Mode (
python run.py --json){ "profile": { "customer_name": "Sarah Connor", "company": "Cyberdyne Systems", "role": "Chief Security Officer", "use_case": "Automating threat intelligence aggregation and incident response", "team_size": "50", "status": "READY", "completeness_score": "High", "missing_fields": [] }, "email": { "subject": "Welcome to Cyberdyne Systems — Let's Elevate Your Threat Intelligence", "body": "Hi Sarah,\n\nWelcome aboard! We are thrilled to partner with Cyberdyne Systems as your team of 50 scales your threat intelligence aggregation and incident response workflows..." } }2. Downstream Piping Example