Agent Manifest File Format

[matoushavlena]

As we move from the Pre-alpha to the Alpha stage, we're revisiting the structure of our agent manifests.

Goals for the new manifest format:

• Include all necessary data for offline discovery, including metadata and interface definitions
• clearly define agent deployment/consumption procedures (how to build and run)
• easily translatable into Kubernetes manifests to streamline production deployments

Current YAML-Based Manifest:

manifestVersion: int # manifest version, incremented on breaking changes

# canonical name incl. domain
# ex. "github.com/i-am-bee/beeai", "github.com/i-am-bee/beeai/nested/folder", "example.com", "example.com/something/else"
# for remotely loaded manifests, the domain of the manifest must match prefix -- e.g. "github.com/i-am-bee/beeai/nested/folder" can be loaded from "https://github.com/i-am-bee/beeai" but not from "https://example.com"
name: str

# how to run the provider server
driver: nodejs | python | container | unmanaged # can later contain new versions like "nodejs@2"

# valid for driver: nodejs | python
# either a NPM/PyPI package name, or "git:..." URL, or (not allowed in remote manifests) "file:..." URL
# can include version for pinning
package: str

# valid for driver: container
# container image identifier (e.g. "docker.io/something/here:latest")
# include version for pinning
image: str

# valid for driver: nodejs | python | container
# command with arguments to run
command: str[]

# whether the server communicates through stdin/stdout, or a HTTP server spawned at $PORT
# for unmanaged provider, only http is available
serverType: stdio | http

mcpTransport: ws | wss | sse | sses | none

# for serverType=http, an array of endpoints
ui: str[] # absolute for "remote" driver, relative for managed drivers

# manifest files can contain multiple entries separated by ---

Proposals

Docker/Ollama like Agentfile

(thank you @gabe-l-hart for the initial proposal)

FROM git+https://github.com/i-am-bee/[email protected]

# Add one or more packages as either local directories or git URLs
ADD git+https://github.com/my-place/my-project

# Configuration through the env
ENV LLM_MODEL="ollama:granite3.2"

# Configuration via beeai parameters??
PARAMETER temperature 0.1

# The module within the set of installed projects to start with.
# This would be understood specifically by the base agent project
ENTRYPOINT "my_project.some_module.doit"

Kubernetes CDR

apiVersion: v1
kind: Agent
metadata:
  name: my-agent
  annotations:
    description: My custom agent
spec:
  runtime: python
  image: docker.io/my-agent:1.2.3
  parameters:
    - name: temperature
      value: 0.1
  entrypoint: "my_project.some_module.doit"

Call to Action

Join the discussion and help shape the manifest format 👋

[psschwei]

Docker/Ollama like Agentfile

What type of artifact would the Agentfile create?

Kubernetes CDR

Would things like runtime and entrypoint already be part of the container?

It would probably be a good idea to model on existing Kubernetes resources (Deployments are a good example), where the spec would include agent-related options (in the deployment example, things like selector and replicas) and then separately a pod template for the containers.

[gabe-l-hart]

What type of artifact would the Agentfile create?

My thought is that the Agentfile would be the equivalent of what the current yaml manifest does with the possible addition of pulling in a project template. It should result in a runnable agent that's referenced from ~/.beeai similar to how the Modelfile pulls in a GGUF file and metadata into ~/.ollama.

[psschwei]

Got it -- I was thinking of the docker build/push workflow, but what you're describing makes total sense. Thanks for the detail!