Small Agents, Big Results

Hands-on workshop for ODSC East 2026 — Jack O'Brien, Subconscious.

A working agent built on a small open-weights model in roughly 150 lines of Python. You give it a GitHub repository URL and it returns a structured tour. The model is Qwen3.6-27B via OpenRouter; tools are exposed through Composio's hosted MCP servers; the procedural recipe lives in a local Skill. Each layer is independent — swap the model, the toolkit, or the skill without touching the others.

Contents

• Architecture
• Prerequisites
• Setup
• Workshop tasks
• Part 2 — Subconscious API
• How it works
• Project layout
• Resources

Architecture

Three independent pieces, composed in agent.py:

Prerequisites

Setup

1. Warm up with Qwen3.6-27B

Open the playground at https://openrouter.ai/qwen/qwen3.6-27b and try a few prompts — plan a refactor, write a tricky regex, explain a stack trace. This is the same model we'll drive in code; the setup is the only thing that changes.

2. Clone and install

git clone https://github.com/subconscious-systems/odsc-east-2026
cd odsc-east-2026
uv sync                 # or: python -m venv .venv && pip install -e .
cp .env.example .env

3. Try Hermes — the open-source production agent

Before building one from scratch, see what a polished open agent looks like. Hermes Agent (the successor to OpenClaw, by Nous Research) is the open-weights counterpart to closed coding agents — full TUI, MCP support, the agentskills.io skills standard, and any backend model you want, including the same Qwen3.6-27B you tried in Step 1.

Install (Linux, macOS, or WSL2 — native Windows is not supported):

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc       # or: source ~/.zshrc

Configure it to use Qwen via OpenRouter, then start a session:

hermes model           # pick: openrouter → qwen/qwen3.6-27b
hermes                 # interactive TUI

Try a real task — summarize the last 5 PRs in this repo, or read agent.py and explain the loop. Notice the patterns: a model-in-a-loop driver, MCP tools, on-demand skills, persistent memory. Everything we'll build by hand in the next steps is here in production form. The full docs are at https://hermes-agent.nousresearch.com/docs.

4. Configure API keys

OpenRouter — provides the model.

1. Sign up at https://openrouter.ai and fund a small balance, or use the free tier.
2. Create a key at https://openrouter.ai/keys.
3. Set OPENROUTER_API_KEY in .env.

Composio — provides the tools as an MCP server.

1. Sign up at https://app.composio.dev.

2. Connections → connect GitHub (one-click OAuth).

3. Settings → API Keys — set the key as COMPOSIO_API_KEY in .env.

4. Mint a personal MCP server URL for the GitHub toolkit:

   uv run scripts/create_mcp_server.py
   

   The script prints a COMPOSIO_MCP_URL=... line. Copy it into .env.

Workshop tasks

Task 1.1 — Tour a GitHub repository

uv run agent.py "Give me a tour of vercel/next.js"

You'll see a trace on stderr:

  · turn 0: read_skill({"skill_name": "repo-tour"})
  · turn 1: GITHUB_GET_FILE_CONTENTS({"repo": "vercel/next.js", "path": "README.md"})
  · turn 2: GITHUB_LIST_DIRECTORY_CONTENTS({"repo": "vercel/next.js", "path": ""})
  · turn 3: GITHUB_GET_FILE_CONTENTS({"repo": "vercel/next.js", "path": "package.json"})
  · turn 4: GITHUB_LIST_PULLS({"repo": "vercel/next.js", "state": "closed", "per_page": 5})
  ...

…and a five-section markdown report on stdout. Try other repositories. agent.py is roughly 120 lines, top to bottom — read it before you move on.

Task 1.2 — Triage a Gmail inbox

A harder task: more tool calls per turn, real data, and no pre-written skill guiding the model.

1. In the Composio dashboard, Connections → connect Gmail (one-click OAuth).

2. Edit scripts/create_mcp_server.py to expose both toolkits:

   TOOLKITS = ["github", "gmail"]
   

3. Re-run the script and replace COMPOSIO_MCP_URL in .env with the new URL.

4. Run a multi-step prompt:

   uv run agent.py "Look at my last 20 emails. Group them by sender, surface \
   anything I haven't replied to in over 2 days, and write a one-line summary \
   of each thread that needs a reply."
   

Watch the trace. The model has to search the inbox, paginate, read individual threads, distinguish sent from received, compare timestamps, and synthesize. Without a skill to guide it, expect occasional missteps — that observation is the lesson.

Bonus: mirror repo-tour and write skills/inbox-triage/SKILL.md. Encode the procedural recipe — search → bucket by sender → check sent folder for replies → flag awaiting >2d → summarize — and re-run the same prompt. A short skill turns an unreliable run into a tight, repeatable one. That is the value Skills provide.

Task 1.3 — Pick any MCP

Composio publishes hundreds of toolkits. Browse the catalog at https://composio.dev/tools, pick something you'd actually use — Slack, Linear, Notion, Stripe, HubSpot, Google Calendar — and repeat the Task 1.2 pattern:

1. Connect the service in the Composio dashboard.
2. Add the toolkit name to TOOLKITS in scripts/create_mcp_server.py.
3. Re-run the script and replace COMPOSIO_MCP_URL in .env.
4. Prompt agent.py against the new tool surface.

The agent loop does not change. The same script handles any MCP-compatible toolkit; only the model's available tools differ. That generality — generic loop, pluggable tools, small model — is the entire point of the workshop.

Part 2 — Subconscious API

Part 1 hand-rolls the agent loop: model call, tool dispatch, message append, repeat. Part 2 hands the loop to Subconscious. You provide instructions and an MCP URL; Subconscious drives the model, calls the tools, and streams the trace into a hosted dashboard.

subconscious_agent.py is about 25 lines — a single client.run(...) call with no while loop and no tool router.

Follow along in the dashboard

1. Sign up at https://subconscious.dev.

2. Dashboard → API Keys — create one and set SUBCONSCIOUS_API_KEY in .env.

3. Keep the dashboard open in a second tab; you will watch the run live.

4. Kick off a run:

   uv run subconscious_agent.py "How many open issues does vercel/next.js have?"
   

5. Switch to the dashboard. The run appears with every model turn, every Composio MCP tool call, and the final answer streaming in. The Composio MCP URL minted in Setup Step 4 is doing the same work as in Part 1 — only the loop driver has moved off your laptop.

Try the Part 1 prompts here too. Same MCP, same tools, fewer lines of code.

How it works

The system prompt contains only skill names and descriptions — never the bodies. The agent calls a read_skill tool when it decides a skill is relevant; the SKILL.md body enters context only at that point. MCP tool results follow the same discipline — fetched on demand, never preloaded. This pattern is progressive disclosure, and it is what lets a small model operate productively against a large tool surface without filling its context with irrelevant material.

To extend the workshop:

• Edit skills/repo-tour/SKILL.md or add a new skill folder under skills/.
• Add additional toolkits in scripts/create_mcp_server.py.
• Swap MODEL at the top of agent.py for any other OpenRouter-supported model.

Project layout

odsc-east-2026/
├── agent.py                        # Part 1 — agent loop (~150 lines)
├── subconscious_agent.py           # Part 2 — Subconscious-driven loop (~25 lines)
├── scripts/
│   └── create_mcp_server.py        # One-time helper to mint a Composio MCP URL
├── skills/
│   └── repo-tour/
│       └── SKILL.md                # Procedural recipe for the GitHub repo tour
├── .env.example                    # API key template
├── pyproject.toml                  # Dependencies (uv-managed)
└── README.md

Resources

• Slides and repository — https://github.com/subconscious-systems/odsc-east-2026
• Skills registry — https://skills.sh (npx skillsadd <owner/repo>/<skill>)
• Composio documentation — https://docs.composio.dev
• Model Context Protocol — https://modelcontextprotocol.io
• OpenRouter — https://openrouter.ai
• Subconscious — https://subconscious.dev

Built for ODSC East 2026.