How msdllcpapers/teal-agents works
Project type and purpose
• Type: Full‑stack, microservices‑style platform for composing AI agents.
• Purpose:
– Core Agent Framework (src/sk‑agents) as a reusable library.
– Multiple “orchestrator” services (assistant, collab, workflow) that coordinate agents, backed by supporting microservices.
File structure
• Top‑level Dockerfiles and Makefile: used to build container images for each orchestrator and the core library.
• shared/ska_utils: shared utility library for configuration, telemetry, module loading.
• src/sk‑agents: Python library for building and invoking agents (plugin loader, chat completion factories, middleware).
• src/orchestrators/*: three orchestrators, each containing:
– an orchestrator service (Python FastAPI app, WebSocket endpoints, config loader, conversation management)
– example directories with Docker Compose, API gateway (Kong), data stores (DynamoDB), frontends (React or HTML).
– supporting “services” sub‑folder in assistant orchestrator (auth, data, telemetry).
Key README insights
• Core Agent Framework → reusable SDK supporting custom plugins, factories, and middleware.
• Orchestrators → define patterns for grouping agents, expose HTTP/WebSocket APIs, rely on shared components.
Main components
a. Client Layer
– React Web App (assistant orchestrator example)
– HTML/JS client (collab orchestrator example)
b. API Gateway
– Kong (routes HTTP/WebSocket traffic to orchestrator and services)
c. Orchestrator Services (per orchestrator)
– AssistantOrchestrator FastAPI service
– CollabOrchestrator service
– WorkflowOrchestrator service
d. Supporting Microservices (assistant orchestrator)
– Auth Service (authenticator)
– Data Service (chat history, context, tickets backed by DynamoDB)
– Ska Services (wrapper around sk‑agents core, custom services)
e. Core Agent Framework
– sk‑agents library (plugin loader, chat completion factory, agent builder)
f. Shared Utilities
– ska_utils (config loader, telemetry, singleton, standardized dates)
g. Data Stores
– AWS DynamoDB tables (chat_history, context, tickets)
– Redis (state store, if used in workflow orchestrator examples)
h. External Services / Plugins
– Weather, Math, Recipient, Test agents (invoked via HTTP or plugin APIs)
– Remote plugin catalog (OpenAPI definitions)
i. Infrastructure / DevOps
– Docker, Docker Compose files, Makefile for building all images
– GitHub Actions workflows for CI/CD
Relationships and data flows
• Orchestrator → Auth Service to validate requests
• Orchestrator → Data Service to read/write chat history and user context
• Orchestrator → sk‑agents library to load/invoke agents (local or remote)
• sk‑agents → External Services (weather, math, etc.) via custom plugins
• Data Service → DynamoDB (CRUD operations)
• Telemetry middleware logs events to telemetry backend
• Docker Compose groups orchestrator + Kong + DynamoDB local + frontend
Architectural patterns and principles
• Microservices: each service has a single responsibility (auth, data, orchestrator).
• Plugin architecture: dynamic loading of agents via config files and module_loader.
• Separation of concerns: UI layer, API gateway, backend services, data stores.
• Middleware layers: telemetry, authentication, context management.
• Infrastructure as code: YAML configs for Docker Compose, Kong, AWS (via local emulation).