Skip to main content

Comprehensive Guide & SDK Documentation

This document merges the conceptual overview of the Instalily AI Agent Platform with a practical Software Development Kit (SDK) guide. It offers both a high-level architectural understanding and the detailed steps developers need to integrate and extend the Instalily multi-agent system.

1. Introduction​

The Instalily AI Agent Platform is an end-to-end environment for building composable, multi-agent AI workflows powered by LLMs (Large Language Models). By combining:

  • Conceptual patterns (e.g. agent architecture, memory management, human-in-the-loop)
  • Technical details (e.g. connectors, environment configs, concurrency controls)

…Instalily delivers enterprise-grade reliability, robust data privacy, and the flexibility to orchestrate advanced generative AI tasks.

1.1 Who Should Read This?​

  • Developers & Architects wanting an internal view of how multi-agent systems can be built and scaled.
  • DevOps & Infra Teams seeking guidance on deploying or self-hosting.
  • Product & Project Managers who wish to see how AI-driven functionality can be integrated with enterprise workflows.

2. Conceptual Overview​

2.1 High-Level Architecture​

Instalily divides the system into distinct layers:

  1. Data Layer
    Connectors, storage solutions, and indexing strategies (e.g., Snowflake, Postgres, vector databases).
  2. Orchestration Layer
    Multi-agent management, concurrency, and workflow definitions.
  3. Execution Engine
    Containerized or serverless deployment, autoscaling, parallelism.
  4. Interface Layer
    Chat UI, Slack integration, or APIs for the end-user or external systems.

Key Architectural Features​

  • Composability: Agents, connectors, and memory components are pluggable.
  • Scalability: A container-based approach ensures we can dynamically increase capacity.
  • Data Isolation: Each tenant uses separate indices or schemas, preventing cross-contamination.
  • Observability: Centralized logging, metrics, and trace data ensure debuggability.

2.2 Agentic Concepts & Multi-Agent Workflows​

  1. Agents: Autonomous units that accept input, possibly invoke LLMs or retrieve data, then produce an output.
  2. Tools: Functions or APIs an agent calls for specialized tasks (DB queries, external integrations).
  3. Orchestrator: A controller that splits complex requests into sub-tasks, delegates them to the right agents, and aggregates results.
  4. Policy / Guardrails: Automatic checks on agent outputs for compliance or brand constraints.

Example Multi-Agent Flow:

2.3 Memory, Persistence & Streaming​

  • Ephemeral Memory: Short-lived context for a conversation or real-time request.
  • Long-Term Memory: Persisted knowledge or user data for advanced personalization.
  • Persistence: Log everything (inputs, outputs) in relational DBs or object stores.
  • Streaming: Agents can stream partial results to the user, especially for large text generation.

2.4 Security & Governance​

  • Tenant Isolation: Each customer has dedicated indexing, ensuring private data boundaries.
  • Compliance: Tools for HIPAA, GDPR, or brand policy enforcement.
  • Auditability: Rich logs trace each agent’s call sequence.

2.5 Deployment & Configuration​

  1. SaaS: Fully managed by Instalily.
  2. Self-Hosted: Customer runs the entire stack in private cloud or on-prem.
  3. Hybrid: Partial resources remain on-prem while orchestration is done in the cloud.

3. Instalily SDK Guide​

This section focuses on the practical aspects of installing, configuring, and extending the Instalily platform at the code level.

3.1 Installation & Setup​

  1. Obtain SDK: Usually via a private PyPI registry or a direct binary.
  2. Initialize Environment: Create a Python virtual environment or use a container base image.
  3. Install: 
    pip install instalily-sdk
  4. Basic Project Structure: 
    your_project/
    ├── agents/
    ├── connectors/
    ├── config/
    ├── main.py
    └── requirements.txt

3.2 Core Classes & Modules​

The SDK organizes classes into subpackages:

  1. instalily.agents

    • BaseAgent: Foundation for custom agents.
    • PolicyAgent: Enforces guardrails.
    • RetrieverAgent: Connects to a vector or RDBMS.

  2. instalily.orchestrator

    • Orchestrator: The “brain” that routes tasks.
    • TaskManager: High-level interface for multi-step workflows.

  3. instalily.connectors

    • Database clients, API clients.

  4. instalily.memory

    • Tools for ephemeral vs. long-term memory.

  5. instalily.utils

    • Helper functions, logging utilities, exception handling.

3.3 Creating Agents & Workflows​

Example: Summarization Workflow

from instalily.agents import SummarizationAgent, PolicyAgent
from instalily.orchestrator import Orchestrator

# Instantiate individual agents
summ_agent = SummarizationAgent(llm="openai-gpt4")
policy_agent = PolicyAgent()

# Build a workflow in code
orchestrator = Orchestrator(
    agents=[summ_agent, policy_agent]
)

input_text = "Some lengthy text about your product..."

# Execute a workflow by specifying tasks
result = orchestrator.run_workflow([
    {"agent": summ_agent, "input": input_text},
    {"agent": policy_agent}
])

print(result)  # Final output after policy check

Workflow Definition: A list of steps. Each step references an agent and optionally an input. Agents can pass outputs to subsequent agents.

3.4 Connector & Tool Integration​

Agents often need to call external data services or LLM endpoints. The SDK offers a consistent interface for “tools.” For instance:

from instalily.connectors import SnowflakeConnector

sf_connector = SnowflakeConnector(
    account="myacc",
    user="service_user",
    password="***",
    database="mydb"
)

# Within an agent's logic:
query_result = sf_connector.run_query("SELECT * FROM products LIMIT 10")

LLM Tools are used similarly, just referencing the relevant provider credentials in your config.

3.5 Logging, Debugging & Observability​

  1. Built-In Logger: Default logging to console, can also route to Splunk, ELK, or CloudWatch.
  2. Debug Mode: The orchestrator can insert breakpoints for interactive stepping.
  3. Tracing: Unique correlation IDs let you reconstruct multi-agent calls.

3.6 Extending the SDK​

  • Custom Agents: Subclass BaseAgent and override observe() and act().
  • Custom Tools: Create a Python function or class, then register it in the orchestrator’s tool registry.
  • Middleware: For cross-cutting concerns like rate-limiting or advanced logging.

4. Putting It All Together​

Below is an end-to-end flowchart illustrating how the concepts and SDK components fit:

  1. User sends a request (via chat, REST call, or other interface).
  2. Task Manager (Orchestrator) splits the request among relevant agents.
  3. Agents may call the LLM, a DB, or memory to gather info.
  4. Policy checks run to ensure compliance.
  5. Final Output is returned.

5. Appendix & Future Directions​

  • Advanced Breakpoints: In upcoming releases, the CLI will support pausing at each agent step for real-time inspection.
  • Time Travel & Versioning: Agents will store versioned prompts for reproducible runs.
  • Reinforcement Learning: Additional features for continuous improvement based on user feedback, including self-supervised tuning.
  • Auto-Summarization of Logs: Large logs can be automatically summarized using system-provided SummarizationAgent.
  • Plugin Ecosystem: A curated list of pre-built domain agents (Salesforce connectors, ERP solutions, etc.) to accelerate enterprise integrations.

For help, please reach out to us at developers@instalily.ai.