What an agent definition is

An agent definition is a YAML file that describes everything an agent needs to run: which LLM to call, which MCP servers to load, which policies to enforce, and which custom skills to install. Agent Guard pulls that definition from an OCI registry (or your local kit store), resolves any base definitions it inherits from, and configures the microVM accordingly before the agent starts.

The point is reproducibility. Instead of telling teammates "install this MCP, set this env var, and use this LLM," you point them at one ref:

bash

agentguard run claude-code --agent-ref myorg/security-review-agent:v1 --workspace ~/projects/myapp

Everything the agent needs comes from that single artifact, signed and version-pinned.

The shape of an agent definition

yaml

apiVersion: agentguard.jozu.dev/v1
kind: AgentDefinition
metadata:
  name: security-review-agent
spec:
  framework: claude-code
  modules:
    - name: primary-llm
      type: llm
      source:
        model: anthropic/claude-sonnet-4-20250514
      auth:
        key: env.ANTHROPIC_API_KEY

    - name: security-scanner
      type: mcp
      source:
        modelkit: myorg/security-scanner-mcp:v1

    - name: review-skill
      type: skill
      source:
        modelkit: myorg/security-audit-skill:v1

    - name: vm-policies
      type: policy
      source:
        modelkit: jozu.ml/jozu/agentguard-policies:vm-standard

A few things to note before going further.

The apiVersion is agentguard.jozu.dev/v1, not gerty.jozu.dev/v1. Policies use the gerty.jozu.dev/v1 API; agent definitions are a separate schema with its own version.

The framework: value must match the agent binary you launch with. If you write framework: claude-code and run agentguard run gemini --agent-ref ..., Agent Guard rejects it. Supported values are claude-code, gemini-cli, codex-cli, and openclaw-cli.

Every module has a name. The name is how modules are addressed during composition (when a derived agent definition inherits from a base and swaps modules out). Within one definition, names must be unique.

The four module types

llm: Configures the LLM provider, model, and credentials. source.model is in <provider>/<model-id> form. auth.key references an environment variable that Agent Guard will pass into the microVM. One LLM module per definition is the common case, though multiple are allowed.
mcp: Adds an MCP server to the agent's tool surface. Two flavors. A modelkit reference (source.modelkit: myorg/scanner:v1) pulls a packed MCP server bundle from a registry and runs it locally inside the microVM over stdio. A remote endpoint (source.endpoint: https://mcp.example.com/mcp with transport: http) wires the agent up to an existing HTTP MCP server. Use config: to pass module-specific configuration (such as allowed_directories: ${workspace} which substitutes to the mounted workspace path).
policy: Adds a policy bundle that Agent Guard enforces inside the microVM. The bundle is an OCI artifact containing one or more YAML policies (ToolPolicy, ArtifactPolicy, GuardrailPolicy). Policies from agent definitions accumulate with policies installed via agentguard policy add. Policy modules have a stronger guarantee than other module types: a derived agent definition cannot remove them.
skill: Adds a custom slash command or skill bundle to the agent. The skill is packaged as a ModelKit and unpacked into the agent's skills directory inside the microVM. Useful for sharing reusable workflows (a /security-audit slash command, for example) across a team.

Where agent definitions come from

Agent definitions are themselves packed as ModelKits using kit pack and pushed to a Hub:

bash

kit pack . -t myorg/security-review-agent:v1
kit push myorg/security-review-agent:v1

You can also keep them local. Short refs without a registry host (my-agent:v1) resolve from your kit local store. Useful for iteration and for air-gapped or offline workflows.

Why this is useful

The agent is reproducible. Any teammate running agentguard run claude-code --agent-ref myorg/security-review-agent:v1 gets the same LLM, MCPs, policies, and skills.

The agent is auditable. The definition is an OCI artifact with a digest. Sign it with cosign and you can verify the agent your team is running is exactly the one your security team approved.

The agent is composable. A derived definition can inherit from a base, swap modules out, and add new ones. Organizations publish a base with their security baseline and let teams build on top.