Multi-agent system built as a modular Python workspace. The project separates reusable agent infrastructure from application-specific agents, making it easy to build new agent applications from shared building blocks.
- Python 3.14+
- uv package manager
- macOS recommended (MLX acceleration for local models)
uv syncRun the docs site:
cd apps/docs
npm install
npm run devRun the chat interface:
- Terminal 1:
make mlflow-ui - Terminal 2:
make registry - Terminal 3:
make chat
The Personal Assistant UI includes an Agent Builder tab powered by agentic-graph.
Run the standalone Agent Builder:
uv run agentic-graphpackages/
agentic/ Core agent SDK (Agent, CoreAgentic, tools, prompts, models)
agentic_graph/ Visual agent builder, validation, runtime sandbox, code generation
agentic_runtime/ Generic agent orchestration framework (runtime, messaging, distributed)
chat/ Reusable Gradio UI building blocks
personal_assistant/ Concrete PA application (5 agents, Gradio UI, domain events)
cli/ CLI interface
registry/ Prompt registry (MLflow-backed)
evaluation/ Evaluation and benchmarking
knowledge_base/ Vector search and note storage
core/ Shared utilities
dataloader/ Dataset loading
workshops/ Educational labs
personal_assistant --> agentic_runtime (framework)
--> agentic (SDK)
--> agentic_graph (visual builder tab)
--> chat (UI library)
--> registry, evaluation, knowledge_base
chat (UI library) --> gradio
agentic_runtime --> agentic (SDK)
agentic_graph --> agentic_runtime (runtime)
--> agentic (SDK)
--> chat (UI library)
--> knowledge_base
cli --> personal_assistant
agentic -- Core agent SDK. Provides Agent, CoreAgentic, model providers, prompt builders, toolsets, and workflow primitives. This is the low-level foundation.
agentic_runtime -- Generic orchestration framework. AgenticRuntime accepts workflows, a router, and output handlers as constructor parameters. Also provides messaging infrastructure, distributed runtime (Apache Iggy, via the Laser SDK), storage, tracing, and turn execution. No application-specific code.
agentic_graph -- Visual agent composition package. Provides a PixiJS-backed graph canvas in Gradio, graph validation, summary/code generation, and a standalone agentic-graph app for prototyping workflows.
chat -- Reusable Gradio UI building blocks: add_message(), append_voice_response(), ChatAppConfig, install_shutdown_handlers(), launch(). Any agent application can compose its UI from these components.
personal_assistant -- The concrete application. Contains 5 specialized agents (manage_notes, organizer, discovery_notes, sage, personalize), a router, domain events, output handlers, the full Gradio UI, and the embedded Agent Builder tab. Entry point: personal-assistant.
| Agent | Purpose |
|---|---|
| manage_notes | CRUD operations on Obsidian notes |
| organizer | PARA-based note classification (event-driven) |
| discovery_notes | Semantic search via RAG knowledge base |
| sage | Decision support using 7-step process (thinking model) |
| personalize | User onboarding and vault configuration |
Run make help to see all available commands.
make install # Install dependencies
make lint # Check code style
make format # Auto-format code
make mypy # Type checking
make clean # Remove compiled files and cachesmake test # All unit tests
make test-pa # Personal assistant tests
make test-runtime # Framework tests
make test-agentic # SDK tests
make test-e2e # Workflow smoke tests (requires live model)
make test-e2e-live # Full end-to-end tests (requires live model)make chat # Gradio chat interface
uv run agentic-graph # Standalone Agent Builder on port 7861
make cli # Interactive CLI
make registry # Prompt registry
make generate-kb # Generate knowledge base- Copy
.env.exampleto.envand setAPI_BASE_URL,LANGSEARCH_API_KEY - Start the stack:
make lab6-up - Open chat at
http://localhost:7860 - Showcase client:
uv run --package workshops workshops lab6 - Stop:
make lab6-down
Settings are loaded from environment variables or .env file. Key settings:
| Variable | Default | Description |
|---|---|---|
MODEL_NAME |
Qwen/Qwen3.5-4B |
Main LLM model |
ORCHESTRATION_MODEL_NAME |
Qwen/Qwen3.5-2B |
Router model |
THINKINK_MODEL |
Qwen/Qwen3.5-9B |
Thinking model (Sage) |
API_BASE_URL |
http://localhost:1234 |
LLM API endpoint |
AGENTIC_TRANSPORT |
in_memory |
in_memory or laser |
LASER_CONNECTION_STRING |
iggy:iggy@127.0.0.1:8090 |
Apache Iggy broker, for laser |
CHAT_SERVER_PORT |
7860 |
Gradio server port |
The communication in agentic runtime is inspired by Emmett by @oskardudycz — a perfect example of event-driven messaging done right. Thank you for the excellent reference that shaped the foundation of this agentic SDK.