Add YAML/JSON agent definition support to CLI

[creatorrr]

trafficstars

User description

Summary

• allow passing YAML or JSON files via --definition
• parse definition file and create agent from it
• document that --definition accepts YAML/JSON

Testing

• ruff format src/julep_cli/agents.py
• ruff check src/julep_cli/agents.py
• pyright (fails: Import "typer" could not be resolved)
• ward (command not found)

---

PR Type

Enhancement, Documentation

---

Description

• Add support for agent creation from YAML/JSON definition files

  • Accepts file path or stdin via --definition
  • Parses YAML or JSON, with error handling
  • Allows override of fields via CLI options

• Update CLI documentation to reflect YAML/JSON support

  • Clarify usage and examples for stdin/file input
  • Update parameter descriptions in docs and reference

---

Changes walkthrough 📝

	Relevant files
Enhancement	agents.py Add YAML/JSON agent definition support and refactor creation logic cli/src/julep_cli/agents.py Add _load_definition to parse YAML/JSON from file or stdin Implement agent creation from definition file with field overrides Improve error handling for parsing and input validation Refactor payload construction for clarity and flexibility +66/-25
Documentation	README.md Update documentation for YAML/JSON agent definition support cli/README.md Update --definition option description to mention YAML/JSON Clarify that definition file can be YAML or JSON Fix stdin example to use -d for both YAML and JSON +4/-4      cli-reference.md Clarify agent definition file format in CLI reference        cli/cli-reference.md Update --definition option to specify YAML/JSON support +1/-1      commands.mdx Document YAML/JSON support for agent definition parameter documentation/julepcli/commands.mdx Update --definition parameter description to mention YAML/JSON +1/-1

---

Need help?

Type /help how to ... in the comments thread for any questions about Qodo Merge usage.

Check out the documentation for more information.

[qodo-merge-for-open-source[bot]]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Error Handling The error handling in _load_definition function could be improved. If a file doesn't exist or can't be read, it will raise a generic exception, but a more specific error message about file access would be helpful. def _load_definition(path: str) -> dict: """Load YAML or JSON agent definition from a file or stdin.""" # AIDEV-NOTE: Support both YAML and JSON for agent definition files. raw = sys.stdin.read() if path == "-" else Path(path).read_text() if path.endswith(".json"): return json.loads(raw) try: return yaml.safe_load(raw) except yaml.YAMLError: return json.loads(raw) Payload Filtering The payload dictionary may contain None values for optional parameters that weren't provided. Consider filtering out None values before sending to the API to avoid potential issues. payload = { "name": name, "model": model, "about": about, "metadata": metadata_dict, "default_settings": default_settings_dict, "instructions": instructions, }

[qodo-merge-for-open-source[bot]]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
General	Improve error handling The current implementation silently falls back to JSON parsing if YAML parsing fails, which could hide actual JSON parsing errors. Add explicit error handling for JSON parsing to provide clearer error messages. cli/src/julep_cli/agents.py [25-28] try: return yaml.safe_load(raw) except yaml.YAMLError: - return json.loads(raw) + try: + return json.loads(raw) + except json.JSONDecodeError as e: + raise ValueError(f"Failed to parse as YAML or JSON: {e}") [ ] Apply / Chat Suggestion importance[1-10]: 8 __ Why: This suggestion adds explicit error handling for both YAML and JSON parsing, providing clearer error messages if both fail. This improves robustness and user experience by not silently swallowing errors.	Medium
	Handle file not found The code doesn't handle file not found errors gracefully. Add proper error handling when reading from a file to provide a user-friendly error message instead of letting the exception propagate. cli/src/julep_cli/agents.py [20-23] -raw = sys.stdin.read() if path == "-" else Path(path).read_text() +try: + raw = sys.stdin.read() if path == "-" else Path(path).read_text() +except FileNotFoundError: + raise ValueError(f"Definition file not found: {path}") if path.endswith(".json"): return json.loads(raw) [ ] Apply / Chat Suggestion importance[1-10]: 7 __ Why: Adding error handling for missing files makes the CLI more user-friendly and prevents unhandled exceptions, but it is a standard practice and not critical for functionality.	Medium
	Improve file format detection The code only checks for .json extension but doesn't handle .yaml or .yml extensions explicitly. Add explicit handling for YAML file extensions to make the format detection more robust. cli/src/julep_cli/agents.py [22-23] if path.endswith(".json"): return json.loads(raw) +elif path.endswith((".yaml", ".yml")): + return yaml.safe_load(raw) [ ] Apply / Chat Suggestion importance[1-10]: 6 __ Why: Explicitly handling YAML file extensions increases robustness and clarity, but the improvement is moderate since the fallback logic already attempts YAML parsing.	Low
[ ] More