docs: improve README with quick start steps and SDK usage example

[Reethikaa05]

User description

Summary

This PR updates the README to make it easier for new developers to get started with Julep.
It adds clearer quick start steps, SDK installation examples, and a minimal workflow example for Python.

Changes

• Expanded the "Getting Started" section with exact commands for both Python and Node.js SDK installation.
• Added a minimal code example for defining and running an AI agent with Julep SDK in Python.
• Linked directly to the Quick Start Guide in the official documentation.
• Improved formatting for readability (code blocks, section headers).

Why This Change?

• New contributors can now run their first Julep agent faster without needing to search in external docs.
• Increases developer adoption by making the onboarding smoother.
• Keeps the README aligned with recent updates (SDK support for GPT-5, CLI improvements, etc.).

Example Snippet Added

from julep import Agent

# Create a simple agent
agent = Agent(
    name="hello-agent",
    memory=True,
    tools=[]
)

response = agent.run("Say hello to the world!")
print(response)


___

### **PR Type**
Enhancement, Tests, Documentation, Bug fix


___

### **Description**
• Added comprehensive Google Sheets and MCP (Model Context Protocol) integrations with CRUD operations and secret management
• Created extensive test suites for chat streaming, middleware validation, usage tracking, and integration functionality
• Restructured cookbook documentation by removing verbose headers and adding new basic tutorials (Hello Agent, Simple Task, Tools, Parallel Steps, RAG)
• Added advanced Hacker News personalized newsletter generator cookbook with web scraping and parallel processing
• Fixed mutable default arguments bug in `list_entries` function
• Added model documentation synchronization script for LiteLLM integration
• Enhanced test fixtures with project support and secret management capabilities
• Updated auto-generated models with configuration changes (auto_run_tools default changed to False)


___

### Diagram Walkthrough


```mermaid
flowchart LR
  A["New Integrations"] --> B["Google Sheets API"]
  A --> C["MCP Protocol"]
  D["Test Coverage"] --> E["Chat Streaming Tests"]
  D --> F["Middleware Tests"]
  D --> G["Integration Tests"]
  H["Cookbook Updates"] --> I["Basic Tutorials Added"]
  H --> J["Advanced Examples Enhanced"]
  H --> K["Documentation Streamlined"]
  L["Bug Fixes"] --> M["Mutable Arguments Fixed"]
  N["Documentation"] --> O["Model Sync Script"]
  N --> P["Type Annotations"]

File Walkthrough

	Relevant files
Enhancement	8 files 11-hacker-news-personalized-generator.ipynb New Hacker News personalized newsletter generator cookbook cookbooks/advanced/11-hacker-news-personalized-generator.ipynb • Added a new comprehensive Jupyter notebook for a Hacker News personalized newsletter generator • Implements a complex workflow that fetches top stories, scrapes content, analyzes relevance, and generates summaries • Includes detailed documentation with overview, features, and step-by-step workflow explanation • Uses multiple integrations including Spider web scraping and parallel processing for efficiency +499/-0  02-Simple-Task.ipynb New simple task basic cookbook                                                      cookbooks/basics/02-Simple-Task.ipynb • Added new basic cookbook demonstrating simple task creation • Includes YAML task definition for echo functionality • Shows execution creation and status checking • Contains related concepts section with documentation links +57/-0    01-Hello-Agent.ipynb New hello agent basic cookbook                                                      cookbooks/basics/01-Hello-Agent.ipynb • Added new basic cookbook showing fundamental agent creation • Demonstrates client initialization, agent creation, and session chat • Includes related concepts section with documentation links • Provides minimal working example for beginners +59/-0    05-RAG-and-Docs.ipynb Add new RAG and documents demonstration notebook                  cookbooks/basics/05-RAG-and-Docs.ipynb • Created new notebook demonstrating Retrieval Augmented Generation with documents • Added session creation with vector recall configuration • Included "Related Concepts" section with documentation links +48/-0    04-Parallel-Steps.ipynb Add new parallel steps demonstration notebook                        cookbooks/basics/04-Parallel-Steps.ipynb • Created new notebook showing parallel step execution example • Added YAML task definition with map and parallelism configuration • Included "Related Concepts" section with documentation links +47/-0    03-Adding-Tools.ipynb Add new tool integration demonstration notebook                    cookbooks/basics/03-Adding-Tools.ipynb • Created new notebook demonstrating tool attachment to agents • Added Wikipedia integration tool creation example • Included "Related Concepts" section with documentation links +52/-0    Tools.py Add Google Sheets and MCP integrations with enhanced API features src/agents-api/agents_api/autogen/Tools.py • Added secrets field to ApiCallDef and ApiCallDefUpdate for secret references • Added params_schema field for API call parameter validation • Added support for "mcp" and "google_sheets" integration providers • Added comprehensive Google Sheets integration classes with CRUD operations • Added MCP (Model Context Protocol) integration classes • Added ParameterSchema and PropertyDefinition classes for schema validation • Added SecretRef classes for secret management +910/-34 Tools.py Mirror Google Sheets and MCP integrations in integrations service src/integrations-service/integrations/autogen/Tools.py • Added secrets and params_schema fields to API call definitions • Added "mcp" and "google_sheets" to supported integration providers • Added complete Google Sheets integration with read/write/batch operations • Added MCP integration for Model Context Protocol support • Added parameter schema validation classes • Added secret reference management classes +891/-40
Documentation	9 files 06-browser-use.ipynb Streamlined browser use cookbook documentation                      cookbooks/advanced/06-browser-use.ipynb • Removed extensive documentation and overview sections from the notebook header • Simplified markdown content by removing detailed task flow descriptions and feature explanations • Updated API key handling to use environment variables instead of hardcoded values • Added related concepts section with documentation links +35/-232 09-companion-agent.ipynb Simplified companion agent cookbook structure                        cookbooks/advanced/09-companion-agent.ipynb • Removed comprehensive documentation header with task definitions and flow descriptions • Simplified client creation section title and removed API key instructions • Fixed YAML schema reference path and corrected output references in task definition • Added execution status checking with time.sleep loop and related concepts section +30/-215 02-sarcastic-news-headline-generator.ipynb Streamlined sarcastic news generator cookbook                        cookbooks/advanced/02-sarcastic-news-headline-generator.ipynb • Removed detailed task overview and implementation documentation from notebook header • Simplified client creation section and removed API key acquisition instructions • Updated YAML schema reference path to use correct source location • Added related concepts section with documentation links at the end +18/-133 07-personalized-research-assistant.ipynb Simplified research assistant cookbook structure                  cookbooks/advanced/07-personalized-research-assistant.ipynb • Removed extensive task definition documentation and flow diagrams from header • Updated API key handling to use environment variables for Brave and LlamaParse • Fixed YAML schema reference path and removed detailed explanatory notes • Added related concepts section with documentation links +22/-175 05-video-processing-with-natural-language.ipynb Streamlined video processing cookbook documentation            cookbooks/advanced/05-video-processing-with-natural-language.ipynb • Removed comprehensive task overview and implementation documentation • Updated environment variable usage for Cloudinary API credentials • Fixed YAML schema reference path and removed explanatory notes • Added related concepts section (with a typo in the last link) +16/-135 00-Devfest-Email-Assistant.ipynb Streamline notebook by removing header documentation and implementation notes cookbooks/advanced/00-Devfest-Email-Assistant.ipynb • Removed extensive header section with branding, badges, and task overview documentation • Removed implementation notes about UUIDs and step references • Simplified notebook structure by removing descriptive markdown cells • Added "Related Concepts" section with documentation links at the end +14/-132 01-website-crawler.ipynb Clean up notebook by removing verbose documentation header cookbooks/advanced/01-website-crawler.ipynb • Removed comprehensive header with branding, task definition, and flow diagrams • Removed UUID management notes and implementation details • Simplified client creation section title • Added "Related Concepts" section with documentation links +13/-127 sync_model_docs.py Model documentation synchronization script for LiteLLM integration src/scripts/sync_model_docs.py • New script to synchronize model information from litellm-config.yaml to documentation • Fetches pricing and feature data from LiteLLM's GitHub repository • Generates markdown tables for models grouped by provider with feature support indicators • Includes cost tier classification and context window formatting • Updates the supported-models.mdx documentation file automatically +453/-0  sessions.py Documentation and type annotation improvements for session exceptions src/agents-api/agents_api/common/exceptions/sessions.py • Added AIDEV-NOTE comments for documentation purposes • Added explicit return type annotation (-> None) to SessionNotFoundError.init method • No functional changes, only documentation and type annotation improvements +4/-1
Bug fix	1 files list_entries.py Fixed mutable default arguments in list_entries function  src/agents-api/agents_api/queries/entries/list_entries.py • Fixed mutable default arguments by changing list parameters to None with proper initialization • Added conditional initialization for allowed_sources and exclude_relations parameters • Includes explanatory comment about avoiding mutable default arguments +7/-2
Tests	5 files test_chat_streaming.py Add comprehensive test suite for chat streaming functionality src/agents-api/tests/test_chat_streaming.py • Created comprehensive test suite for chat streaming functionality • Added tests for streaming response format, document references, and usage tracking • Added helper functions for collecting stream content and managing usage records • Added tests for custom API key usage and developer tag tracking • Added database integration tests for usage record creation +860/-0  fixtures.py Enhance test fixtures with project support and secret management src/agents-api/tests/fixtures.py • Added test_project fixture for project-related testing • Updated test_agent fixture to include project association • Added custom_scope_id fixture and updated execution fixtures • Added clean_secrets fixture for secret management testing • Updated model validation patch path reference +55/-5    test_task_execution_workflow.py Test updates for workflow execution with database connection handling src/agents-api/tests/test_task_execution_workflow.py • Added functools import and custom base_evaluate_with_pool function for database connection handling • Updated test mocks to handle workflow context exceptions with _NotInWorkflowEventLoopError • Modified activity execution calls to include additional parameters like developer_id, agent_id, task_id • Updated test assertions to match new parameter structure for integration and system calls • Added database pool creation and connection handling in evaluation tests +277/-79 test_middleware.py New middleware test suite for usage and cost validation    src/agents-api/tests/test_middleware.py • Added comprehensive test suite for HTTP middleware functionality • Tests cover usage cost checking, user account validation, and cost limit enforcement • Includes tests for different user types (free, paid, inactive) and request methods • Tests middleware behavior for session creation/deletion with cost limits • Validates proper error handling and response codes for various scenarios +597/-0  test_mcp.py MCP integration test suite with transport and tool testing src/integrations-service/tests/test_mcp.py • New comprehensive test suite for MCP (Model Context Protocol) integration • Tests MCP provider registration, tool listing, and tool execution functionality • Includes tests for HTTP and SSE transport connections with proper mocking • Validates timeout handling, error scenarios, and response normalization • Tests SDK availability checks and transport validation +430/-0
Configuration changes	1 files Tasks.py Auto-generated model updates with formatting and default changes src/agents-api/agents_api/autogen/Tasks.py • Added import for JinjaTemplate from .Common module • Reformatted field definitions with better line breaks for readability • Removed continue_ field from PromptItem class • Changed default value of auto_run_tools from True to False in PromptStep and PromptStepUpdateItem classes • Updated documentation comments to reflect the new default behavior +176/-128
Miscellaneous	1 files Agents.py Auto-generated agent models and request/response schemas  src/agents-api/agents_api/autogen/Agents.py • New auto-generated file containing Pydantic models for agent-related operations • Defines models for Agent, CreateAgentRequest, UpdateAgentRequest, PatchAgentRequest • Includes model information classes like ModelInfo and ListModelsResponse • Contains comprehensive field validation and documentation for agent properties +294/-0
Additional files	101 files .agentignore +3/-1      setup.sh +112/-0  .cursorindexignore +0/-150  .cursorrules +0/-158  .env.example +12/-2    CONTRIBUTING.md +17/-17  LICENSE [link]    README-CN.md +98/-1655 README-FR.md +98/-1660 README-JA.md +98/-1657 SUPPORT.md +4/-4      bandit-security-check-python-agents-api.yml +10/-7    changelog-sync.yml +98/-0    claude-changelog-pr.yml +81/-0    claude-code-review.yml +70/-0    claude-docs-manual.yml +92/-0    claude-docs-pr.yml +122/-0  claude.yml +58/-0    generate-changelog.yml +2/-6      generate-openapi-code-from-typespec.yml +6/-6      lint-agents-api-pr.yml +4/-4      lint-integrations-service-pr.yml +4/-4      publish-cli-prerelease.yml +142/-0  sync-model-docs.yml +51/-0    test-agents-api-pr.yml +7/-5      test-integrations-service-pr.yml +4/-4      translate-readme.yml +26/-35  typecheck-agents-api-pr.yml +5/-5      .mcp.json +29/-0    AGENTS.md +329/-0  CHANGELOG.md +45/-1    CLAUDE.md +0/-98    CLAUDE.md +0/-98    README.md +81/-595 CLAUDE.md +0/-41    pg_query_step.py +0/-22    create_agent.py +0/-102  create_or_update_agent.py +0/-117  patch_agent.py +0/-98    update_agent.py +0/-70    create_or_update_user.py +0/-77    create_user.py +0/-74    patch_user.py +0/-80    update_user.py +0/-64    chat.py +0/-132  model_validation.py +0/-19    test_agent_queries.py +0/-201  test_get_doc_search.py +0/-180  test_litellm_utils.py +0/-25    test_pg_query_step.py +0/-92    entries.html +16/-0    entry.html +15/-0    footer.html +7/-0      head.html +11/-0    header.html +10/-0    package.json +11/-0    style.css +104/-0  archives.html +28/-0    entries.html +48/-0    entry.html +61/-0    error.html +12/-0    feed.rss +20/-0    footer.html +7/-0      head.html +11/-0    header.html +20/-0    home-summary.html +13/-0    package.json +51/-0    public.html +23/-0    robots.txt +3/-0      script.js +3/-0      search.html +27/-0    sitemap.xml +21/-0    style.css +390/-0  tagged.html +22/-0    2025-06-17.md +12/-0    2025-06-23.md +14/-0    2025-06-25.md +9/-0      2025-06-26.md +11/-0    2025-06-30.md +23/-0    2025-07-02.md +17/-0    2025-07-03.md +19/-0    2025-07-04.md +12/-0    2025-07-05.md +13/-0    2025-07-08.md +11/-0    2025-07-09.md +18/-0    2025-07-31.md +8/-0      2025-08-06.md +7/-0      2025-08-07.md +11/-0    2025-08-08.md +12/-0    2025-08-15.md +9/-0      2025-01-31.md +16/-0    2025-02-14.md +16/-0    2025-04-11.md +16/-0    2025-05-09.md +8/-0      2025-05-21.md +38/-0    2025-06-23.md +34/-0    2025-06-30.md +13/-0    2025-07-04.md +18/-0    2025-07-05.md +18/-0    2025-07-08.md +14/-0    Additional files not shown

---

[qodo-merge-for-open-source]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

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

🧪 PR contains tests

🔒 Security concerns Secrets handling: Several notebooks hardcode placeholder API keys (e.g., JULEP_API_KEY, SPIDER_API_KEY) while others correctly use environment variables (Cloudinary, Browserbase). Replace hardcoded placeholders with environment variable reads and add guidance to avoid committing secrets. Also ensure the social badges/links in notebooks do not expose tokens.

⚡ Recommended focus areas for review Possible Issue The get_story_details tool is configured with a placeholder URL (https://example.com) but later referenced to call HN item endpoints dynamically; ensure the tool definition supports templated per-invocation URLs or update the base URL to avoid 404s. " method: GET\n", " url: \"https://example.com\"\n", " headers:\n", " Content-Type: application/json\n", "\n", Robustness Several evaluate/map steps assume presence of keys like url, top_comments[0], and JSON parsing of model output; add guards for missing fields and try/except around json.loads to prevent execution failures on malformed responses. " $ f'''\n", " Story to analyze:\n", " Title: $ {{ _[\"title\"] }}\n", " URL: $ {{ _[\"url\"] }}\n", " Score: $ {{ _[\"score\"] }}\n", " Content preview: $ {{ _[\"content\"]}}\n", " Top comment: $ {{ _[\"top_comments\"][0][\"text\"] }}\n", "\n", " Return format: \"relevance_score\" from 0 to 100\n", " Return only a JSON object with the relevance score (0-100).\n", " Return ONLY raw JSON without markdown code blocks\n", " '''\n", " unwrap: true\n", "label: score_stories\n", "\n", "# Step 14: Combine original stories with their relevance scores\n", "# Creates tuples of story data and personalization score\n", "- evaluate:\n", " scored_stories: '$ [{{\"story\": steps[\"final_stories_with_comments\"][\"output\"][\"stories_with_comments\"][i], \"relevance_score\": json.loads(steps[\"score_stories\"][\"output\"][i])[\"relevance_score\"]}} for i in range(len(steps[\"score_stories\"][\"output\"]))]'\n", "label: combine_scores\n", Typo/Link In "Related Concepts", the third link text duplicates 'Tasks' and includes a malformed URL suffix; fix the markdown link to 'Tools' with correct URL. "## Related Concepts\n", "\n", "- [Agents](https://docs.julep.ai/concepts/agents)\n", "- [Tasks](https://docs.julep.ai/concepts/tasks)\n", "- [Tasks](https://docs.julep.ai/concepts/tasks)lep.ai/concepts/tasks)" ]

[qodo-merge-for-open-source]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Avoid infinite loop on execution failure Modify the while loop to check for terminal states like "failed" or "cancelled" in addition to "succeeded" to prevent a potential infinite loop. cookbooks/advanced/03-trip-planning-assistant.ipynb [583-587] -while execution.status != "succeeded": +while execution.status not in ["succeeded", "failed", "cancelled"]: time.sleep(5) execution = client.executions.get(execution.id) print("Execution status: ", execution.status) print("-"*50) [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 8 __ Why: This suggestion correctly identifies a potential infinite loop if the execution enters a terminal state other than "succeeded", which is a significant bug in the polling logic.	Medium
	Prevent error on stories without comments Add a check to prevent an IndexError when accessing top_comments for stories that have no comments. cookbooks/advanced/11-hacker-news-personalized-generator.ipynb [339-352] - role: user content: >- $ f''' Story to analyze: Title: $ {{ _["title"] }} URL: $ {{ _["url"] }} Score: $ {{ _["score"] }} Content preview: $ {{ _["content"]}} - Top comment: $ {{ _["top_comments"][0]["text"] }} + Top comment: $ {{ _["top_comments"][0]["text"] if _["top_comments"] else "N/A" }} Return format: "relevance_score" from 0 to 100 Return only a JSON object with the relevance score (0-100). Return ONLY raw JSON without markdown code blocks ''' [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 8 __ Why: The suggestion correctly identifies a potential IndexError if a story has no comments and _["top_comments"][0] is accessed. The proposed fix is robust and prevents the task from failing, which is a significant improvement to the code's reliability.	Medium
	Correct invalid keyword argument Correct the keyword argument from agent to agent_id in the client.sessions.create call to prevent a runtime error. cookbooks/basics/05-RAG-and-Docs.ipynb [17] -"session = client.sessions.create(agent=agent.id, recall=True, recall_options={'mode':'vector','limit':5})\n", +"session = client.sessions.create(agent_id=agent.id, recall=True, recall_options={'mode':'vector','limit':5})\n", [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 8 __ Why: The suggestion correctly identifies a bug in a new example notebook where an incorrect keyword argument agent is used instead of agent_id, which would cause the code to fail.	Medium
	Prevent crashes from missing environment variables Replace os.environ with os.getenv to check for the JULEP_API_KEY and raise a ValueError with a helpful message if it's not set. cookbooks/advanced/03-trip-planning-assistant.ipynb [48] -JULEP_API_KEY = os.environ["JULEP_API_KEY"] +JULEP_API_KEY = os.getenv("JULEP_API_KEY") +if not JULEP_API_KEY: + raise ValueError("JULEP_API_KEY environment variable not set. Please set it to your Julep API key.") [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 7 __ Why: The suggestion improves robustness and user experience by providing a clear error message when a required environment variable is missing, instead of letting the program crash with a KeyError.	Medium
	Add model validation for conditional fields Add a Pydantic model_validator to the GoogleSheetsSetup class to enforce that service_account_json is provided when use_julep_service is False. src/agents-api/agents_api/autogen/Tools.py [1772-1794] +from pydantic import model_validator + class GoogleSheetsSetup(BaseModel): """ Setup parameters for Google Sheets integration """ ... use_julep_service: StrictBool """ Whether to use Julep's built-in Google Sheets service account. If true, no credentials needed. If false, service_account_json is required. """ service_account_json: str | None = None """ Base64 encoded service account JSON for authentication. Required when use_julep_service is false. Users can provide their own service account for better isolation and quota management. """ default_retry_count: Annotated[int, Field(ge=1, le=10)] = 3 """ Default number of retry attempts for API calls """ + @model_validator(mode="after") + def check_service_account(self) -> "GoogleSheetsSetup": + if not self.use_julep_service and not self.service_account_json: + raise ValueError( + "service_account_json is required when use_julep_service is False" + ) + return self + [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 7 __ Why: The suggestion correctly points out that the conditional requirement described in the docstring is not enforced, and proposes adding a validator to improve the model's robustness.	Medium
Security	Load API keys from environment Load openweathermap_api_key and brave_api_key from environment variables instead of using hardcoded placeholders to improve security and usability. cookbooks/advanced/03-trip-planning-assistant.ipynb [105-106] -openweathermap_api_key = "YOUR_API_KEY" -brave_api_key = "YOUR_API_KEY" +import os +openweathermap_api_key = os.getenv("OPENWEATHERMAP_API_KEY", "YOUR_API_KEY") +brave_api_key = os.getenv("BRAVE_API_KEY", "YOUR_API_KEY") + [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 6 __ Why: The suggestion correctly points out that loading keys from the environment is a better practice for security and usability, especially in an example notebook.	Low
General	Fix duplicated documentation link Replace the duplicate "Tasks" documentation link with a more relevant link to "Tools" documentation to avoid redundancy. cookbooks/advanced/00-Devfest-Email-Assistant.ipynb [357-359] "- [Agents](https://docs.julep.ai/concepts/agents)\n", "- [Tasks](https://docs.julep.ai/concepts/tasks)\n", -"- [Tasks](https://docs.julep.ai/concepts/tasks)\n" +"- [Tools](https://docs.julep.ai/concepts/tools)\n" [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 3 __ Why: The suggestion correctly identifies a duplicated link in a newly added section of the notebook and proposes a relevant replacement, which is a minor quality improvement.	Low
More

[ellipsis-dev]

⚠️ This PR is too big for Ellipsis, but support for larger PRs is coming soon. If you want us to prioritize this feature, let us know at [email protected]

---

Generated with ❤️ by ellipsis.dev