A LangGraph personal co-worker: a worker agent with tools (web search, browser, files, Python, Wikipedia) and an evaluator that loops until success criteria are met or the user must respond.
Based on the Agentic AI course Sidekick pattern (worker → tools → evaluator loop).
- Python >=3.10, <3.14
- uv
- Playwright Chromium for browser tools
- API keys in
.env(see below)
From the project root (langgraph/sidekick):
uv sync
uv run playwright install chromium
cp .env.example .env
# Edit .env with your keys| Variable | Required | Description |
|---|---|---|
OPENAI_API_KEY |
Yes | OpenAI API key |
OPENAI_MODEL |
No | Model name (default: gpt-4o-mini) |
TAVILY_API_KEY |
Recommended | Primary web search via Tavily |
SERPER_API_KEY |
Recommended | Fallback Google search via Serper |
PLAYWRIGHT_HEADLESS |
No | true to run Chromium headless; false to show the browser window |
PUSHOVER_TOKEN / PUSHOVER_USER |
No | Mobile push notifications via Pushover |
LANGSMITH_* |
No | Optional tracing in LangSmith |
uv run sidekickOr:
uv run python -m sidekick.appGradio prints a local URL (for example http://127.0.0.1:7860). Open it in your browser, wait for the page to finish loading (the agent initializes on load), then enter a request and success criteria and click Go!.
After code or .env changes, stop the server with Ctrl+C and run the command again.
End-to-end walkthrough: research IT relocation in Europe, save markdown reports, and send Pushover summaries.
Start the app with uv run sidekick. The Gradio UI opens with an empty chat, a request box, a success-criteria box, and Reset / Go! buttons.
Request — describe your background and what you want Sidekick to do:
I am in Amazon India as a SDE-III… I am working towards finding IT Backend Jobs in Europe. Can you give me a list of countries which allows easy re-location… Can you also give me relevant companies… Please create separate markdown files and send 2 separate push notifications directly with country names and companies names.
Success criteria — how the evaluator should judge completion:
The results should be backed by authentic web sources.
Click Go! to start the worker → tools → evaluator loop.
Sidekick searches the web, may browse pages, and returns a structured answer in the chatbot. The reply lists countries and companies with brief notes and source links for transparency.
The agent writes deliverables under workspace/ using the save_file tool (for example european_countries_for_it_jobs.md and it_companies_in_europe.md). Open them in your editor to review the full markdown reports.
If LangSmith tracing is enabled in .env, you can inspect each run: worker LLM calls, search tool invocations, save_file writes, and token/cost breakdowns.
When PUSHOVER_TOKEN and PUSHOVER_USER are set, Sidekick sends two push notifications—one summarizing countries and one summarizing companies—so you get the highlights on your phone without opening the app.
flowchart LR
START --> worker
worker -->|tool calls| tools
tools --> worker
worker -->|no tools| evaluator
evaluator -->|retry| worker
evaluator -->|done| END
- Worker — plans and acts with tools until it has a non-tool reply.
- Tools — search (Tavily with Serper fallback), Playwright browser, file I/O, structured
save_file, Python REPL, Wikipedia, optional Pushover. - Evaluator — checks the reply against your success criteria; loops back to the worker if not satisfied.
Outputs and saved files go under workspace/.
sidekick/
├── src/sidekick/
│ ├── graph.py # LangGraph StateGraph + Sidekick class
│ ├── tools.py # Playwright, search, save_file, Pushover, etc.
│ ├── app.py # Gradio UI entry point
│ └── assets/ # README demo screenshots
├── workspace/ # Agent-written files (created at runtime)
├── .env.example
├── pyproject.toml
└── uv.lock