skill

ollama-adk-samples

A collection of sample agents built with Agent Development Kit (ADK) for Ollama Models

DanHUMassMed/ollama-adk-samplescommunitylistedunreviewed

Set up

Skills are installed by placing their folder where your agent loads skills.

Download ZIP from GitHub Open the repository

The download comes from github.com/DanHUMassMed/ollama-adk-samples itself, not from our server, so what you get is exactly what its author published.

Install instructions come from the README

Skills do not use an MCP config. Follow the steps in the README below.

README

synced Oct 22, 2026

Local Google ADK Samples (`ollama-adk-samples`)

A collection of local-first rewrites of the official Python agent samples from google/adk-recipes. These projects demonstrate how to build, orchestrate, evaluate, and deploy autonomous multi-agent systems using the Google Agent Development Kit (ADK) while running 100% locally and privately.

All cloud dependencies (Gemini APIs, Vertex AI Vector Search, Google Grounding Search, and cloud sandboxes) have been substituted with local open-source counterparts:

LLM Inference: Ollama via ADK's LiteLlm provider (gemma4:26b, gemma4:31b, gpt-oss:20b).
Web Search & Grounding: Local SearXNG instances queried via the Model Context Protocol (MCP) (searxng_mcp) or asynchronous HTTP connectors.
Vector Storage & Retrieval: Local ChromaDB with Hugging Face SentenceTransformers (all-MiniLM-L6-v2).
Code Execution: Dockerized sandboxes via ContainerCodeExecutor or local isolation executors.
Observability & Tracing: Local Arize Phoenix instance via OpenInference instrumentation.

🏛 Local Architecture Overview

graph TD
    User([User / Browser]) <--> ADKUI[ADK Web UI / FastAPI Server]
    
    subgraph "Google ADK Multi-Agent Core"
        RootAgent[Root Coordinator / Orchestrator Agent]
        SubAgent1[Specialized Subagent / Planner]
        SubAgent2[Domain Worker / Evaluator Agent]
        RootAgent <--> SubAgent1
        RootAgent <--> SubAgent2
    end
    
    ADKUI <--> RootAgent
    
    subgraph "Local-First Execution Layer"
        Ollama[Ollama Server\n:11434/v1\ngemma4 / gpt-oss]
        SearXNG[SearXNG Meta-Search\n:32768\nvia FastMCP stdio]
        Chroma[ChromaDB Local Store\nSentenceTransformers]
        DockerSandbox[Docker Container\nSandbox Code Execution]
        Phoenix[Arize Phoenix\n:8081\nOpenInference Traces]
    end
    
    SubAgent1 <-->|LiteLlm Provider| Ollama
    SubAgent2 <-->|LiteLlm Provider| Ollama
    SubAgent1 <-->|MCPToolset| SearXNG
    SubAgent2 <-->|Vector Retrieval Tool| Chroma
    SubAgent2 <-->|ContainerCodeExecutor| DockerSandbox
    RootAgent -.->|Telemetry| Phoenix

Key Differences from Upstream `google/adk-recipes`

Component	Upstream `google/adk-recipes`	Local Rewrite (`ollama-adk-samples`)
Model Runtime	Google Gemini 1.5/2.0 via Vertex AI / Google GenAI Studio	Local Ollama running `gemma4:26b`, `gemma4:31b`, or `gpt-oss:20b` via `LiteLlm`
Search Engine	Google Search Grounding (`google-genai` tools)	Self-hosted SearXNG via Model Context Protocol (FastMCP stdio)
Vector DB	Vertex AI Vector Search / Cloud Datastore	Local persistent ChromaDB with `all-MiniLM-L6-v2` embeddings
Document Parsing	Cloud Document AI / Gemini Multimodal Input	Local PDF parsing (`pypdf`) via ADK `before_model_callback` hooks
Code Execution	Vertex AI Code Execution Sandbox	Local Docker container sandboxes (`ContainerCodeExecutor`)
Telemetry	Google Cloud Trace / Logging	Local Arize Phoenix UI via OpenInference telemetry

📂 Projects Catalog

Subdirectory	Upstream Recipe	Primary Architecture	Key Local Substitution	Launch Command
`RAG/`	`RAG`	Single-agent Document Q&A with strict citations	Local ChromaDB + SentenceTransformers	`uv run adk web RAG/rag_agent`
`academic_research/`	`academic_research`	Hierarchical Multi-Agent (Coordinator, Search, Synthesis)	PDF text hook (`pypdf`) + SearXNG MCP	`uv run adk web academic_research`
`agent_skills_tutorial/`	`agent_skills_tutorial`	Progressive Disclosure with `SkillToolset`	Local `gemma4:26b` running 4 skill patterns	`uv run adk web agent_skills_tutorial`
`coder_agents/`	`coder_agents`	Multi-strategy code generation & execution	Dockerized sandbox (`ContainerCodeExecutor`)	`uv run adk web coder_agents`
`deep_search/`	`deep_search`	Sequential & Loop Agent research pipeline	SearXNG MCP + Custom Vite/React UI	Backend: `adk api_server`Frontend: `npm run dev`
`financial_advisor/`	`financial_advisor`	Hierarchical Multi-Agent (4 expert financial analysts)	Local SearXNG HTTP connector + Ollama	`uv run adk web financial_advisor`
`searxng_search/`	Grounding Search	FastMCP server & client connector	Local SearXNG instance on `:32768`	`uv run adk web searxng_search`
`youtube_analyst/`	`youtube_analyst`	Multi-Agent + Dynamic Plotly/Matplotlib visualization	`WebSafeLiteLlm` wrapper + local chart generation	`uv run adk web youtube_analyst`

🔍 Detailed Project Summaries

1. RAG (Retrieval-Augmented Generation)

An accurate, verifiable document question-answering agent designed for complex documents (such as financial 10-K filings).

Core Components:
- Ingestion pipeline (load-data.ipynb): Parses PDFs page-by-page using pypdf and langchain_text_splitters.RecursiveCharacterTextSplitter. Generates embeddings using sentence-transformers/all-MiniLM-L6-v2 and persists them to a local chroma_db_chunks/ database with rich metadata (page numbers, source filenames, character offsets).
- Agent (rag_agent/agent.py): Configures ask_rag_agent on LiteLlm(model="openai/gpt-oss:20b") with the ask_chromadb tool.
- Evaluation (eval/test_eval_phoenix.py): Automated local evaluation suite benchmarking retrieval precision and groundedness using Arize Phoenix and OpenInference.
Run Command:
```
uv run adk web RAG/rag_agent
```

2. Academic Research

An autonomous literature analysis workflow that ingests a seminal research paper, searches for recent citing literature, and synthesizes novel future research directions.

Multi-Agent Hierarchy:
- academic_coordinator: Root orchestrator. Intercepts PDF uploads via an ADK before_model_callback hook (callbacks.py) that parses PDF binary data into plain text dynamically before it reaches the model.
- academic_websearch_agent: Queries local SearXNG via FastMCP (searxng_mcp) for recent citing publications published within the last 1–2 years.
- academic_newresearch_agent: Formulates novel, high-utility research proposals combining insights from the seminal paper and recent developments.
Run Command:
```
uv run adk web academic_research
```

3. Agent Skills Tutorial

Demonstrates Google ADK's SkillToolset pattern, enabling agents to dynamically discover, load, and execute specialized capabilities on demand without bloating the core system prompt.

The 4 Skill Implementations:
1. Inline Skill (seo-checklist): Programmatic Python-defined rules directly inside code.
2. File-Based Skill (blog-writer): Loaded from local directories containing standard SKILL.md instruction files and templates.
3. External Skill (content-research-writer): Simulates third-party community-contributed skills.
4. Meta Skill (skill-creator): Self-extending capability allowing the agent to read specification guidelines and generate new SKILL.md skill packages dynamically.
Run Command:
```
uv run adk web agent_skills_tutorial
```

4. Coder Agents

A comparative implementation of four different code execution and sandboxing strategies for code-generation agents:

Sub-Agents:
- unsafe_agent/: Direct in-process execution using UnsafeLocalCodeExecutor (no sandboxing).
- w_tools_agent/: Custom tool executing code via Python's exec() (no isolation).
- container_agent/: Isolated container execution using ContainerCodeExecutor with standard python:3.11-slim.
- sandbox_agent/: Full Docker sandbox using a customized docker-sandbox image equipped with scientific computing libraries (pandas, numpy, scipy).
Run Command:
```
uv run adk web coder_agents
```
(Select any of the 4 agents via the UI dropdown).

5. Deep Search

An advanced, iterative multi-agent research and report composition system featuring a full-stack architecture with a dedicated FastAPI backend and a custom React + Vite frontend.

Pipeline Architecture:
- interactive_planner_agent: Root agent that interacts with the user to negotiate and refine a structured research plan.
- research_pipeline (SequentialAgent):
  - section_planner: Breaks the research plan into report sections.
  - section_researcher: Conducts initial deep searches using SearXNG FastMCP.
  - iterative_refinement_loop (LoopAgent): Repeatedly executes research_evaluator (critic agent) and enhanced_search_executor, controlled by a custom EscalationChecker agent that terminates the loop upon reaching passing quality.
  - report_composer_with_citations: Synthesizes research notes into a publication-grade markdown report with automatic citation replacement.

Frontend & Backend Run:

# Terminal 1 - Backend API Server:
cd deep_search/backend
uv run adk api_server . --allow_origins="*"

# Terminal 2 - Vite React Frontend:
cd deep_search/frontend
npm run dev

6. Financial Advisor

A hierarchical multi-agent advisory assistant that coordinates a team of specialized financial analysts to guide users through structured stock analysis, trading strategy, and risk assessment.

Specialized Subagents:
- data_analyst: Queries ticker metrics and financial news via an asynchronous SearXNGConnector.
- trading_analyst: Formulates trading strategies aligned with user risk preferences and investment horizons.
- execution_analyst: Specifies order execution tactics, timing, and fee/slippage management.
- risk_analyst: Assesses portfolio vulnerabilities, drawdown risks, and volatility boundaries.
Run Command:
```
uv run adk web financial_advisor
```

7. SearXNG Search Agent

The reference implementation and foundational connector for local search across the repository.

Components:
- FastMCP Server (searxng_mcp/server.py): Wraps a local SearXNG engine instance into an MCP standard search tool over stdio transport.
- Search Connector (searxng_mcp/connector.py): Asynchronous client connecting to http://localhost:32768 (configurable).
- Search Agent (searxng_search_agent/agent.py): An ADK agent equipped with MCPToolset to test queries and verify search grounding.
- Documentation (SearXng_How-to-setup.pdf): Step-by-step setup guide for SearXNG.
Run Command:
```
uv run adk web searxng_search
```

8. YouTube Analyst ("YouBuddy")

An AI-native "Attention Guardian" and consultative YouTube analysis agent focused on Return on Attention (RoA).

Core Features:
- YouTube Data Integration (tools.py): Direct retrieval of video transcripts (youtube-transcript-api), video metadata, comments, and channel statistics.
- Data Visualization Subagent (visualization_agent): Dynamically executes Python code to produce interactive HTML charts (Plotly) and static graphics (Matplotlib).
- Dynamic Skills: Includes skills for KOL discovery (kol-discovery), audience sentiment analysis (sentiment-analysis), and debate synthesis (debate-synthesizer).
- Web UI Compatibility: Uses WebSafeLiteLlm to prevent FastAPI schema serialization conflicts with LiteLlm internal objects.

Run Command:

export YOUTUBE_SEARCH_API="your-youtube-api-key"
uv run adk web youtube_analyst

🛠 Local Environment & Services Setup

1. Prerequisites

Python: >=3.14 (managed via uv)
Package Manager: uv
Ollama: Installed and running on http://localhost:11434
Docker: (Required for coder_agents container sandboxes and SearXNG)

2. Pull Required Ollama Models

Ensure you have the required open models pulled to your local Ollama daemon:

# General purpose and skills agents
ollama pull gemma4:26b

# Deep reasoning and synthesis agents
ollama pull gemma4:31b

# RAG and Deep Search agents
ollama pull gpt-oss:20b

3. Start Local SearXNG Instance

Run SearXNG locally using Docker (configured to listen on port 32768 by default):

docker run -d \
  --name searxng \
  -p 32768:8080 \
  -v "${PWD}/searxng:/etc/searxng" \
  -e "SEARXNG_BASE_URL=http://localhost:32768/" \
  searxng/searxng:latest

4. Install Dependencies

Initialize the virtual environment and install all project dependencies using uv:

make dev
# or equivalently:
uv sync --extra dev --prerelease allow

5. Apply the OpenInference Instrumentation Hot-Patch

[!IMPORTANT] The upstream package openinference-instrumentation-google-adk contains a bug when parsing google-adk prerelease version strings (e.g. 2.0.0a3), causing crashes during adk web startup. Run our automated patch script whenever you rebuild or refresh your .venv:

uv run python patch_openinference.py

(See README-HOTPATCH.md for full technical details).

📊 Local Observability & Tracing

All agents support full telemetry tracing into a local Arize Phoenix server.

Launch Phoenix UI:

make phoenix
# or:
PHOENIX_HOST=127.0.0.1 PHOENIX_PORT=8081 uv run phoenix serve

Access the Dashboard: Open http://127.0.0.1:8081 in your browser to inspect agent tool calls, step latencies, token consumption, and intermediate thinking traces.

💻 Development & Automation Commands

This repository includes a Makefile for standard tasks:

Command	Action
`make dev`	Bootstraps `.venv` dependencies via `uv sync --extra dev --prerelease allow`.
`make phoenix`	Starts local Arize Phoenix tracing server on `http://127.0.0.1:8081`.
`make lint`	Runs `ruff format`, `ruff check`, and `mypy` type validations.
`uv run adk web <dir>`	Launches the interactive Google ADK Web UI for the given project.
`uv run python patch_openinference.py`	Hot-patches `.venv` openinference package for `google-adk` prereleases.

📜 Attribution & License

Original recipes and agent concepts adapted from Google's google/adk-recipes.
Distributed under the Apache License 2.0.