BeeAI provides multiple ways to work with agents in your local environment. This guide explains how to add and manage agents effectively.

​
Adding Agents

​
Auto-Discovery for Local Development

When developing ACP-compliant agents locally, BeeAI automatically discovers them without manual setup:

# Example: Run an ACP agent on port 8000 
uv run my_agent.py

# The agent automatically appears in BeeAI
beeai list  # Your agent will be visible here

Auto-discovered agents appear in both the CLI and web UI automatically. No manual import needed!

​
From GitHub Repositories

Import agents directly from GitHub repositories that contain proper Dockerfiles. Try this ready-to-go starter project:

beeai add "https://github.com/i-am-bee/beeai-platform-agent-starter"

More import options:

# Specify a version or branch
beeai add "https://github.com/i-am-bee/custom-agent.git#v1.0.0"
beeai add "https://github.com/i-am-bee/custom-agent.git#develop"

# Import from specific subdirectory
beeai add "https://github.com/i-am-bee/custom-agent.git#:agents/my-agent"

# Combined version and path
beeai add "https://github.com/i-am-bee/multi-agent-repo.git#v2.1.0:agents/specialized-agent"

Requirements for GitHub import:

  • Repository must contain a Dockerfile in the root or specified path
  • Agent must follow ACP protocol standards
  • Repository must be publicly accessible

​
From Docker Images

Add agents from pre-built Docker images:

# From GitHub Container Registry
beeai add ghcr.io/i-am-bee/beeai-platform/community/aider:latest

# From Docker Hub
beeai add myuser/my-agent:v1.0

# From private registry
beeai add registry.example.com/team/custom-agent:latest

​
From Local Filesystem

Add local agents:

# Build an add an agent from current directory
beeai add .

# Build an add an agent from specific directory
beeai add /path/to/my-agent

This will build the agent and add it to your agent list.

If the command above is failing, or you only need to build the agent image, you can run the steps separately:

# Build agent only
beeai build /path/to/my-agent

# Build with custom tag
beeai build . --tag my-custom-agent:dev

# Build without importing (for testing)
beeai build . --no-import

After a successful build you’ll get a message like ✅ Successfully built agent: beeai.local/path-to-my-agent-db09b8:latest, you can add this image to the platform by beeai add beeai.local/path-to-my-agent-db09b8:latest

​
Removing Agents

When you no longer need an agent:

# Remove by agent name
beeai remove <agent-name>

# Alternative commands (aliases)
beeai uninstall <agent-name>
beeai delete <agent-name>
beeai rm <agent-name>

​
Checking Agent Status

You can check the status of your agents at any time:

beeai list