DOCSEARCHbyAlgolia
Submit Docs

Ark Agentic Runtime

repository·main·Indexed 19 days ago

https://github.com/mckinsey/agents-at-scale-ark

An agentic runtime for Kubernetes designed to build, host, and scale distributed AI agents using a declarative, provider-agnostic approach. Ark manages Kubernetes Custom Resources including Agents, Teams, Queries, Tools, Models, and MCPServers. It includes a Completions Engine executor, a dedicated CLI, and the Ark Query Extension (v1) for passing context to execution engines via the A2A protocol.

Tokens
263.2K
Snippets
686
Records
1.2K
Agent score
64%

What's inside ark

  1. What is ARK - Agentic Runtime for Kubernetes

    main

    ARK (Agentic Runtime for Kubernetes) is an open-source toolkit that extends Kubernetes using Custom Resource Definitions (CRDs) and services to build and run agentic workloads. It functions similarly to how Argo extends Kubernetes for workflows, allowing you to manage AI agents, multi-agent teams, and tool integrations using declarative Kubernetes specifications.

    ARK provides managed resources for:

    • AI model configurations: Defining the models your agents use.
    • Autonomous agents: Specifying individual agent behaviors.
    • Multi-agent teams: Orchestrating groups of agents.
    • Tool integrations: Connecting agents to external tools.
    • Memory persistence: Managing state and long-term memory for agents.

  3. What is Ark?

    main
    Ark is a declarative, Kubernetes-native toolkit for building and hosting distributed AI agents. It allows you to define agents as Kubernetes custom resources (specifying prompts, tools, and model references) rather than writing proprietary code. This approach ensures portability, scalability, and provider agnosticism, allowing you to swap between providers like OpenAI, Anthropic, Google, Azure, or local Ollama without code changes.

  4. Overview of available ARK services

    main

    ARK provides several categories of services:

    Core Services

    • Completions Engine: The default execution engine for Ark queries.
    • ARK Broker: Provides in-memory storage with SSE streaming support. It can optionally use Postgres for messages/events and Redis Streams for completion chunks.

    ARK API Services

    Includes the ARK API which provides:

    • Native ARK REST APIs.
    • OpenAI-compatible endpoints.
    • A2A Gateway endpoints for agent-to-agent communication.

    Execution Engines

    • LangChain Execution Engine: An A2A server specifically for LangChain agent execution.

    Development Tools

    • ARK Dashboard: A Next.js-based web interface for managing ARK.
    • ARK API: A REST API for managing ARK resources.

  5. Overview of Ark Vulnerability Management

    main

    Ark uses a multi-channel approach to identify, prioritize, and remediate security vulnerabilities. The system integrates several scanning tools into the CI/CD pipeline and uses a baseline/whitelist model for prioritization.

    Scanning Channels

    SourceTypeWhere it runs
    JFrog Xray build scanSCA / supply chainCI (.github/workflows/cicd.yaml, jfrog-xray-scan job)
    JFrog Xray container scanImage vulnerabilityCI (xray-container-scan job, matrix over 9 images)
    SonarQubeSAST / code qualityCI (.github/workflows/sonar_scan.yaml, self-hosted runner)
    DependabotDependency updatesGitHub (weekly per ecosystem)
    GitleaksSecret scanningCI (.github/workflows/gitleaks.yaml) and pre-commit hook
    Penetration testingManual assessmentExternal, periodic

  7. Understand Ark's Design Principles

    main

    Ark's development is guided by five core pillars designed to ensure agentic systems are suitable for production in large, complex, and regulated environments. When building or extending the platform, align your implementation with these high-level goals:

    1. User-Centric Design: Focus on persona-driven development (tailored experiences for developers vs. business users) and progressive disclosure (revealing complexity only as needed).
    2. Developer Experience (DX) Excellence: Use open-source, mainstream technologies, ensure frictionless integration into existing workflows, and provide transparent debugging capabilities.
    3. Consumer Accessibility: Provide implementation abstraction (hide technical details from end users), no-code empowerment (visual/natural language interfaces), and headless support (expose all capabilities via APIs and protocols like MCP).
    4. Operational Excellence: Prioritize resilience, observability, security-by-default, and protective defaults (safe settings by default with clear warnings).
    5. Resource Management and Scale: Ensure cloud-native resource transparency, elastic scaling with guardrails, and isolation by design to prevent interference between workloads.

  8. Access the Ark Marketplace

    main

    The Ark Marketplace is maintained in a separate repository from the core Ark project. To find available components such as executors, services, MCP servers, agents, and demos, you must visit the dedicated marketplace repository and its documentation site.

  9. Explore the Ark samples directory structure

    main

    The samples/ directory is organized by functional category to demonstrate different QBAF (QuantumBlack Agent Factory) capabilities. Use these directories to find patterns for specific implementations:

    • quickstart/: Basic setup and getting started.
    • agents/: Agent examples and configurations.
    • teams/: Team coordination and strategies.
    • tools/: Tool integrations and APIs.
    • workflows/: Complete end-to-end workflows.
    • queries/: Query patterns and targeting.
    • memory/: Memory and conversation persistence.
    • models/: Model configurations (LLMs).
    • mcp/: Model Context Protocol integrations.

  10. Understand the ARK CI/CD and Deploy pipelines

    main

    ARK uses two primary pipeline types to manage its components:

    1. CI/CD Pipeline: Triggered on every push. It performs library builds, single-platform container builds (AMD64) for testing, E2E testing, SonarQube code quality scanning, and release preparation. It uses a setup-container-cache-registry job to determine the registry (forks use their own GHCR namespace, while internal PRs use the organization's registry).

    2. Deploy Pipeline: Run on demand. It can deploy specific artifacts including:

      • Documentation to GitHub Pages
      • Multi-arch Containers to a configured registry
      • Helm charts to a configured registry (under /charts)
      • ARK CLI to NPM
      • ARK Python SDK to PyPI
      • Ark to distribution, AWS, or GKE test environments.

    Artifacts and version tags can be selected manually when running the pipeline.

  11. Overview of Ark Custom Resources (CRDs)

    main

    Ark extends Kubernetes using Custom Resource Definitions (CRDs) within the ark.mckinsey.com API group. These resources are the fundamental building blocks of the platform and are managed by the Ark controller.

    Key characteristics:

    • Management: Resources can be managed using standard Kubernetes tools like kubectl, GitOps workflows, the Ark API, or the Ark dashboard.
    • Namespacing: Most resources are namespaced. The ArkConfig resource is the exception; it is cluster-scoped.
    • API Versions: Most resources use v1alpha1, while A2AServer and ExecutionEngine use v1prealpha1.

  12. What is Ark?

    main

    Ark is a platform for running AI agents and multi-agent systems on Kubernetes. It treats every component of an agentic system—such as models, agents, teams, and queries—as a Kubernetes custom resource.

    Because Ark is built on Kubernetes, you can manage your agents using standard Kubernetes tools and patterns, including:

    • kubectl for resource management.
    • GitOps for declarative configuration.
    • RBAC for security and access control.
    • Namespaces for multi-tenancy and isolation.