How julep-ai/julep works
Main Components
• Agents API – This is the core backend service that manages agents, tasks, workflows, and orchestrates complex operations. Note that it is organized in its own “agents-api” directory with subdirectories for activities, routers, queries, and workers.
• Integrations Service – This service handles third-party integrations (e.g., with Brave, Email, Cloudinary, etc.). Its structure under “integrations-service” indicates a similar modular microservice approach.
• CLI and SDK Clients – The CLI tool (in the “cli” folder) and SDK libraries (both Python and Node.js) represent the client components through which developers interact with the backend.
• Gateway – A service (under “gateway”) that likely serves as a reverse proxy, managing incoming requests and possibly enforcing security, authentication, or routing them to the correct backend component.
• Blob Store and Memory Store – Storage systems for handling files and persistent state (look at “blob-store” and “memory-store” directories). They might store large binary objects or support caching and session data.
• Scheduler – Found under “scheduler”; this component likely manages timed or event-based job execution and might integrate with Temporal given the presence of temporal-related profiles in deployment.
• Monitoring – Support components (under “monitoring”) that include Docker Compose configurations for Grafana and Prometheus, indicating real-time observability and metrics collection.
• Documentation, Typespecs, and Schemas – Though not part of the runtime, these provide important insight into APIs and the expected formats (e.g., “typespec” and “schemas” directories).
Relationships and Interactions
• Client Layer:
– End users (developers or automated systems) interact with Julep via the CLI and SDKs.
– They submit task definitions and commands that trigger workflows.
• API & Gateway:
– Requests from clients flow into the Gateway, which then dispatches them to either the Agents API or the Integrations Service.
– The Agents API handles core processing (orchestrating tasks, managing state, and handling workflow logic).
• Internal Communication:
– The Agents API likely communicates with the integrations service (and possibly the blob-store and memory-store) to run tools or persist data.
– The Scheduler orchestrates task executions (possibly triggering processes in the worker components under Agents API or Integrations Service).
• Data Storage & Monitoring:
– Memory Store, Blob Store, and a database (as indicated by numerous migration files) act as persistent stores.
– Monitoring setups gather metrics, track execution statuses, and feed logs back to an operations dashboard.
• External API Calls:
Architectural Patterns and Design Principles
• Microservices: The clear separation between agents, integrations, gateway, storage, and scheduling indicates a microservice architecture.
• Modular Organization: Each service is organized in a self-contained directory, following principles such as “separation of concerns” and “single responsibility.”
• Service Communication: Likely using RESTful APIs between services with defined schemas (provided in the “typespec” and “schemas” folders).
• Asynchronous & Parallel Processing: The workflow engine supports parallel tasks and asynchronous processing (e.g., “parallelism” in workflow YAML specifications).
• Containerization & Deployment: With Docker Compose files across services (for agents-api, integrations-service, gateway, blob-store, memory-store, etc.), container orchestration is central to deployment.
• Observability: Integration with monitoring tools (Prometheus, Grafana) suggests that logging, metrics, and observability are key network components.