Quickstart
Run Orchid locally in under ten minutes with the basketball demo.
This guide takes you from a fresh clone to your first agent reply in under ten minutes, using the basketball demo — a self-contained pair of agents (NBA stats expert and sports psychologist) with PostgreSQL persistence and Qdrant RAG, running on local models via Ollama.
Prerequisites#
You need Docker Desktop (or Docker Engine + Compose v2) and Ollama running on the host with three models pulled:
ollama pull llama3.2
ollama pull nomic-embed-text
ollama pull minicpm-vllama3.2 drives the agents, nomic-embed-text powers embeddings, and minicpm-v handles image parsing in document uploads.
Clone#
The examples live in a dedicated repository. Clone it and enter the basketball example:
git clone https://github.com/gadz82/orchid-examples
cd orchid-examples/basketball
cp .env.example .env # optional — the defaults work with local OllamaRun the basketball demo#
The example ships with its own Compose file that starts the API, PostgreSQL, Qdrant, the web UI, and the MCP gateway. Ollama stays on your host — the API reaches it through host.docker.internal.
docker compose up --buildThe first build takes a few minutes to pull base images and install Python dependencies. Subsequent starts are fast because Docker caches the layers. Once you see Application startup complete in the logs, you have:
- API:
http://localhost:8080 - Web UI:
http://localhost:3000 - MCP gateway:
http://localhost:9000/mcp - Qdrant:
http://localhost:6333
For a zero-infrastructure alternative (no Docker, SQLite + ChromaDB instead of PostgreSQL + Qdrant), try the Recipes example which runs entirely locally with Ollama.
First call#
Create a chat session, then send your first message:
# 1. Create a chat and capture its id
curl -s -X POST http://localhost:8080/chats \
-H "Content-Type: application/json" -d '{}' \
| python3 -c "import sys, json; print(json.load(sys.stdin)['id'])"
# 2. Send a message (the endpoint expects multipart/form-data)
curl -X POST http://localhost:8080/chats/<chat_id>/messages \
-F "message=Tell me about LeBron James"Or open http://localhost:3000 and chat from the UI.
The basketball agent calls the get_player_stats tool, retrieves career stats from the example's data store, and returns a structured analysis. Ask the psychologist anything about player motivation or team dynamics — it has its own dedicated tools.
What just happened?#
Orchid loaded basketball/agents.yaml, which declares the agents, their tools, and the cross-agent skills. The tools are implemented as OrchidTool subclasses in the example's Python package, and the entire agent configuration lives in YAML. The framework built a LangGraph supervisor graph, which routes your message to the right agent based on content and available tools.
The supervisor also manages conversation history across turns, so follow-up questions work naturally. When you ask about a player's mental state, the supervisor automatically forwards relevant context from the basketball agent to the psychologist agent as part of a multi-step skill.
Behind the scenes, chat history is persisted to PostgreSQL via the orchid-storage-postgres plugin and responses are streamed via Server-Sent Events. The RAG pipeline is configured but not indexed yet — uploading a PDF through POST /chats/{chat_id}/upload would make it retrievable in future turns.
Next steps#
Explore the configuration reference for all orchid.yml and agents.yaml options. Browse the examples for more complex scenarios including helpdesk, restaurant ordering, MCP auth flows, and RAG strategies. The best practices guide covers production-ready patterns for scaling Orchid in a real deployment.
When the work has a stable shape, move from chat to a data pipeline: a typed, run-scoped DAG that mixes deterministic code, LLM jobs, agents, decisions, maps and sub-pipelines — invokable from Python, HTTP, the CLI, an agent tool or a Bloom trigger. The direct pipeline example is the quickest end-to-end starting point.