Agentcontrolplane

<div align="center"> <h1>Agent Control Plane (ACP)</h1> </div>

ACP (Agent Control Plane) is a cloud-native orchestrator for AI Agents built on Kubernetes. It supports long-lived outer-loop agents that can process asynchronous execution of both LLM inference and long-running tool calls. It's designed for simplicity and gives strong durability and reliability guarantees. It embraces concepts from 12-factor-agents for agents that make asynchronous tool calls like contacting humans or delegating work to other agents.

:warning: Note - ACP is in alpha.

<div align="center"> <h3>

Discord | Documentation | Examples

</h3>

</div>

Table of Contents

• Key Features
• Architecture
  • Core Objects
• Getting Started
  • Prerequisites
  • Setting Up a Local Cluster
  • Deploying ACP
  • Creating an Agent and Running your first task
  • Adding Tools with MCP
  • Using other language models
  • Delegating to a Sub-Agent
  • Incorporating Human Approval
  • Incorporating Humans as Tools
  • Cleaning Up
• Design Principles
• Contributing
• License

Architecture

<img width="1918" alt="Screenshot 2025-04-10 at 9 00 58 AM" src="https://github.com/user-attachments/assets/854a2496-0e6c-438f-aee5-6805263fface" />

Core Objects

• LLM: Provider + API Keys + Parameters
• Agent: LLM + System Prompt + Tools
• Tools: MCP Servers, Humans, Other Agents
• Task: Agent + User Message + Current context window
• ToolCall: A single tool call that occurred during a Task

Getting Started

Prerequisites

To run ACP, you'll need:

• kubectl - Command-line tool for Kubernetes brew install kubectl
• OpenAI API Key - For LLM functionality https://platform.openai.com

To run ACP locally on macos, you'll also need:

• kind - For running local Kubernetes clusters brew install kind (other cluster options should work too)
• Docker - For building and running container images brew install --cask docker

Setting Up a Local Cluster

kind create cluster

Add your OpenAI API key as a Kubernetes secret

For Anthropic and other providers, see Using other language models

kubectl create secret generic openai \
  --from-literal=OPENAI_API_KEY=$OPENAI_API_KEY \
  --namespace=default

Deploying ACP

[!TIP] For better visibility when running tutorial, we recommend starting a stream to watch all the events as they're happening, for example:

kubectl get events --watch

Deploy the ACP operator to your cluster:

kubectl apply -f https://raw.githubusercontent.com/humanlayer/agentcontrolplane/refs/heads/main/acp/config/release/latest.yaml

<details> <summary>Just the CRDs</summary>

kubectl apply -f https://raw.githubusercontent.com/humanlayer/agentcontrolplane/refs/heads/main/acp/config/release/latest-crd.yaml

</details> <details> <summary>Install a specific version</summary>

kubectl apply -f https://raw.githubusercontent.com/humanlayer/agentcontrolplane/refs/heads/main/acp/config/release/v0.1.0.yaml

</details>

This command will build the operator, create necessary CRDs, and deploy the ACP components to your cluster. <!-- Updated Name -->

Creating Your First Agent and Running your first task

1. Define an LLM resource

echo 'apiVersion: acp.humanlayer.dev/v1alpha1
kind: LLM
metadata:
  name: gpt-4o
spec:
  provider: openai
  parameters:
    model: gpt-4o
  apiKeyFrom:
    secretKeyRef:
      name: openai
      key: OPENAI_API_KEY
' | kubectl apply -f -

graph RL
    LLM
    Secret

    Credentials --> Secret

    subgraph LLM
      Provider
      Credentials
      ModelParameters
    end

Check the created LLM:

kubectl get llm

Output:

NAME     PROVIDER   READY   STATUS
gpt-4o   openai     true    Ready

<details> <summary>Using `-o wide` and `describe`</summary>

kubectl get llm -o wide

Output:

NAME     PROVIDER   READY   STATUS   DETAIL
gpt-4o   openai     true    Ready    OpenAI API key validated successfully

kubectl describe llm gpt-4o

Output:

Name:         gpt-4o
Namespace:    default
Labels:       <none>
Annotations:  <none>
API Version:  acp.humanlayer.dev/acp
Kind:         LLM
Metadata:
  Creation Timestamp:  2025-03-21T20:18:17Z
  Generation:          2
  Resource Version:    1682222
  UID:                 973098fb-2b8d-46b3-be49-81592e0b8f4e
Spec:
  API Key From:
    Secret Key Ref:
      Key:   OPENAI_API_KEY
      Name:  openai
  Provider:  openai
  Parameters:
    Model: gpt-4o
Status:
  Ready:          true
  Status:         Ready
  Status Detail:  OpenAI API key validated successfully
Events:
  Type    Reason               Age                 From            Message
  ----    ------               ----                ----            -------
  Normal  ValidationSucceeded  32m (x3 over 136m)  llm-controller  OpenAI API key validated successfully

</details>

2. Create an Agent resource

echo 'apiVersion: acp.humanlayer.dev/v1alpha1
kind: Agent
metadata:
  name: my-assistant
spec:
  llmRef:
    name: gpt-4o
  system: |
    You are a helpful assistant. Your job is to help the user with their tasks.
' | kubectl apply -f -

graph RL
    Agent
    LLM
    Secret

    LLMRef --> LLM
    Credentials --> Secret


    subgraph LLM
      Provider
      Credentials
      ModelParameters
    end

    subgraph Agent
      LLMRef
      SystemPrompt
    end

Check the created Agent:

kubectl get agent

Output:

NAME           READY   STATUS
my-assistant   true    Ready

<details> <summary>Using `-o wide` and `describe`</summary>

kubectl get agent -o wide

Output:

NAME           READY   STATUS   DETAIL
my-assistant   true    Ready    All dependencies validated successfully

kubectl describe agent my-assistant

Output:

Name:         my-assistant
Namespace:    default
Labels:       <none>
Annotations:  <none>
API Version:  acp.humanlayer.dev/acp
Kind:         Agent
Metadata:
  Creation Timestamp:  2025-03-21T22:06:27Z
  Generation:          1
  Resource Version:    1682754
  UID:                 e389b3e5-c718-4abd-aa72-d4fc82c9b992
Spec:
  Llm Ref:
    Name:  gpt-4o
  System:  You are a helpful assistant. Your job is to help the user with their tasks.

Status:
  Ready:          true
  Status:         Ready
  Status Detail:  All dependencies validated successfully
Events:
  Type    Reason               Age                From              Message
  ----    ------               ----               ----              -------
  Normal  Initializing         64m                agent-controller  Starting validation
  Normal  ValidationSucceeded  64m (x2 over 64m)  agent-controller  All dependencies validated successfully

</details>

Running Your First Task

Create a Task to interact with your agent:

echo 'apiVersion: acp.humanlayer.dev/v1alpha1
kind: Task
metadata:
  name: hello-world-1
spec:
  agentRef:
    name: my-assistant
  userMessage: "What is the capital of the moon?"
' | kubectl apply -f -

graph RL
    Agent
    LLM
    Secret

    LLMRef --> LLM
    Credentials --> Secret
    AgentRef --> Agent


    subgraph LLM
      Provider
      Credentials
      ModelParameters
    end

    subgraph Agent
      LLMRef
      SystemPrompt
    end

    subgraph Task
      AgentRef
      UserMessage
    end

Check the created Task:

kubectl get task

Output:

NAME            READY   STATUS   PHASE         PREVIEW                            OUTPUT
hello-world-1   true    Ready    FinalAnswer   What is the capital of the moon?   The Moon does not have a capital. It is a natural satellite of Earth and does not have any political or administrative divisions like a country does. There are no permanent human settlements on the Moon, so it does not have a capital city.

You can describe the task to see the full context window

kubectl describe task hello-world-1

Output:

# ...snip...
Status:
  Context Window:
    Content:  You are a helpful assistant. Your job is to help the user with their tasks.

    Role:     system
    Content:  What is the capital of the moon?
    Role:     user
    Content:  The Moon does not have a capital, as it is not a governed entity like a country. It is a natural satellite of Earth. However, if you are referring to human activity on the Moon, there is no permanent settlement or colony established there as of now. Most activities on the Moon have been in the form of missions or landings conducted by various space agencies.
    Role:     assistant

# ...snip...

  Status Detail:  LLM final response received
Events:
  Type    Reason                     Age   From             Message
  ----    ------                     ----  ----             -------
  Normal  ValidationSucceeded        65s   task-controller  Task validation succeeded
  Normal  SendingContextWindowToLLM  65s   task-controller  Sending context window to LLM
  Normal  LLMFinalAnswer             64s   task-controller  LLM re