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

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

Sep 27 '25 16:09 Reethikaa05

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)"
]

Sep 27 '25 16:09 qodo-free-for-open-source-projects[bot]

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 <!-- /improve --more_suggestions=true -->

Sep 27 '25 16:09 qodo-free-for-open-source-projects[bot]

:warning: 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 :heart: by ellipsis.dev

Sep 27 '25 16:09 ellipsis-dev[bot]