Skip to content

docs

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

docs

README.md

Continuum Documentation

Reference documentation for the Continuum agentic framework (shyftlabs-continuum on PyPI, importable as continuum).

Note: every example in these docs has been verified against the actual source under src/continuum/. Imports, parameter names, defaults, and signatures match the codebase as of the latest release.

Where to start

If you've never used Continuum before, read in this order:

  1. installation.md — Python 3.13 setup, env vars, troubleshooting
  2. agent.md — the BaseAgent / AgentRunner mental model; the most important file
  3. llm.md — provider routing (no LiteLLM), structured outputs, context compression
  4. tools.md — connecting MCP servers, tool-context capture, run artifacts
  5. memory.md and session.md — persistent memory and conversation history
  6. observability.md — tracing, metrics, error reporting
  7. core.md — the DI container, lifecycle, health checks, protocols
  8. temporal/ — durable workflows with approval gates

Module index

Module Doc What it gives you
continuum.agent agent.md BaseAgent, AgentRunner, 9 workflow patterns, handoffs
continuum.llm llm.md LLMClient, provider routing, structured outputs, compression
continuum.memory memory.md mem0 + Qdrant long-term memory; IntelligentMemoryClient
continuum.session session.md Redis-backed conversation history
continuum.tools tools.md MCP servers (Stdio/SSE/StreamableHTTP), ToolExecutor, artifacts
continuum.observability observability.md Langfuse tracing, metrics, error reporter
continuum.core core.md Container, OrchestratorLifecycle, health checks
continuum.temporal temporal/ Durable workflows, approval gates
continuum.config, protocols, exceptions core.md §7-§8 Settings, runtime-checkable protocols, exception hierarchy

Conventions

  • Async-first — every public API is async; wrap in asyncio.run(main()). The few sync entry points are clearly marked (*_sync methods).
  • Direct provider SDKs — Continuum calls OpenAI / Anthropic / Gemini directly. No LiteLLM anywhere.
  • Provider routing by model prefix — gemini/... → Gemini, claude-… / anthropic/... → Anthropic, everything else → OpenAI.
  • MCP-native tooling — every tool is exposed via the Model Context Protocol; no bespoke adapters.
  • Three IDs that travel together — trace_id (Langfuse), session_id (Redis), and run_id (mem0). The framework keeps them synchronized via contextvars.
  • OPENAI_API_KEY is required at startup — mem0's default embedder is OpenAI. Set the key, change the embedder provider, or disable memory entirely.

Runnable example apps

The repository ships a playground/ tree with end-to-end example apps that exercise different feature combinations:

Path Demonstrates
../playground/sdk_feature_test/ SDK-feature smoke test
../playground/memory-modes-demo/ All four memory scopes (USER / AGENT / RUN / SHARED)
../playground/commerce-chat/ Plan-and-execute multi-agent + MCP tool restriction
../playground/fetch-agent/ Tool-using agent with MCP fetch server
../playground/assortment/ FastAPI-served agent endpoint

A separate continuum-hackathon kit packages a pre-built wheel and minimal starter examples for downstream users; this repository is the source of truth.

Working with AI assistants

The repo ships AI-assistant configuration so Claude Code / Codex / Cursor can write Continuum code correctly without prompting:

Out-of-date references in legacy material

If you stumble across older docs, READMEs, or example code that mentions any of the following, they are stale:

  • LiteLLM — removed in framework commit 657607a. Use LLMClient with direct provider SDKs.
  • SessionClient.add_message(session_id, role=..., content=...) — the real signature is add_message(session_id, message: ChatMessage).
  • from continuum.agent import RouterAgent, create_router_agent with a Route(target=...) — the field is Route(agent_name=..., description=...).
  • from continuum.memory import MemoryClient with client.add(text, user_id=...) — works, but add() accepts strings, lists of strings, OR lists of {role,content} dicts; the messages-style is the recommended path.