Skip to content

Next steps

You finished the Quickstart and have a streaming agent running locally. Here is where to go from here.

Learn the primitives in depth

Read real projects

  • examples/support-agent is the runnable companion to the 3-step killer demo tutorial. Fork it, set ANTHROPIC_API_KEY, and run uv sync && ajolopy dev to see every primitive in action against a real provider.
  • examples/web-research is the canonical "wire an external HTTP API as a @Tool" reference (AJ-65). A Researcher agent that calls the Tavily search API through one @Tool and folds the results into a Markdown-cited answer through a second pure-Python @Tool. Ships with an @Eval regression suite plus pre-built Dockerfile.prod + fly.toml.
  • examples/oncall-agent is the focused @MCP demo (AJ-63). Wires the canonical GitHub MCP server into a small on-call agent so the model can search issues / PRs / commits while triaging incidents. Boots cleanly without a GITHUB_TOKEN — the agent's local @Tool keeps answering when the MCP server is unhealthy.
  • examples/local-ollama is the no-API-key runnable example (AJ-66). It runs @Agent + @Tool + @Stream against a local Ollama server through Ajolopy's universal OpenAI-compatible provider — install Ollama, ollama pull llama3.3, uv sync && ajolopy dev, and the streaming code reviewer answers POST /chat entirely on your laptop.
  • examples/memory-assistant is the persistent-assistant reference for @Agent(memory="redis://..."). A SessionScopedMemory wrapper plus a request ContextVar partition chat history per session_id, so two users hitting the same /chat endpoint see independent transcripts in Redis. Ships with a docker-compose.yml, a Dockerfile.prod, and a 5-row eval suite whose memory_isolation metric catches cross-session leaks.
  • dogfood/docsbot is Ajolopy's own docs bot — the first dogfood app (AJ-54). Answers questions about the framework using an in-memory Retriever subclass over the project's own docs/ tree, exercises @Agent + @Tool + @Stream + @Eval end-to-end, and ships pre-generated Dockerfile.prod + fly.toml.
  • examples/contextual-rag is the RAG flagship example (AJ-67). Contextual chunking (every chunk ships the parent section's summary), hybrid retrieval (0.4 keyword + 0.6 semantic-hash), and citation-enforcing evals (addresses_query LLM-judge plus two deterministic checks for the [path#section] citation block and the right cited section). Documents the upgrade path to QdrantRetriever / PgvectorRetriever for real embeddings.
  • Dogfood apps roadmap. A small set of end-to-end Ajolopy projects maintained alongside the framework — the same way NestJS ships nest-cli examples. Tracked as AJ-54 and AJ-55.

Put it in production

  • Observability recipes. Five cookbooks plugged in via the otel extra: Langfuse · Sentry · Grafana stack · Honeycomb · Datadog. Same pipeline, different exporter — pick one and you have traces + cost dashboards in under 10 minutes.
  • Deploy templates. Fly.io, Railway, Render, Vercel, and a universal Dockerfile — all generated by ajolopy new when you opt in.

Contribute

Ajolopy is built in the open and tracks every piece of work on a PM-style board in the repo.

  • board.json is the single source of truth for what is ready, in_progress, blocked, in_review, or done.
  • AGENTS.md documents the claim / branch / transition protocol for both human and AI contributors.
  • specs/ holds the prose spec for every board item — the design contract you build against.
uv run python tools/board.py list      # see what is open
uv run python tools/board.py next      # see what to pick up next

File issues or open discussions at github.com/jcocano/Ajolopy.

Help and feedback