Hyland Connect

angelborroy

AI agents are quickly becoming the new microservices. They encapsulate logic, connect to tools, and can be composed together to solve complex tasks. But just like containers were before Docker Compose, running and orchestrating agents has felt clunky and inconsistent.

That changes with Docker new cagent: an open-source, YAML-driven runtime for defining and running AI agents. With cagent, you can describe how your agents behave, what tools they can use, and how they route tasks… then launch them with a single command.

In this post, we’ll introduce cagent and show Alfresco developers how to use it in a practical example that combines content search and audit logging.

What is cagent?

At its core, cagent is a multi-agent runtime:

Agents are defined declaratively in YAML
Each agent can use tools exposed via Model Context Protocol (MCP) backends
Agents can be composed into hierarchies, where a root agent delegates to specialized ones
It runs anywhere: local CLI, TUI, API, or inside a container

Think of it as Docker Compose, but for AI agents. You no longer need custom glue code to orchestrate agents: just write a spec, point it to your tools, and run.

Why Alfresco developers should care

Alfresco repositories are rich ecosystems, for instance they contain:

Audit and compliance require structured logs and queries
Content operations rely on metadata, renditions, and search

With cagent, you can expose Alfresco MCP backends as agent tools. That means developers can query repositories with natural language, and the agent will automatically route the request to the right tool.

It’s a clean bridge between LLMs and Alfresco Content Services.

Step-by-step: Alfresco + cagent

Let’s walk through a concrete use case where one agent can search content and retrieve audit entries. We are taking the 2 Alfresco MCP Servers used in the blog post Running an Agent Mesh with Alfresco Community as starting point.

1. Clone and start the Alfresco Agent Mesh

git clone https://github.com/aborroy/simple-alfresco-agent-mesh
cd simple-alfresco-agent-mesh
docker compose up

This brings up two MCP backends:

Audit MCP: http://localhost:8081/mcp
Docs MCP: http://localhost:8003/mcp

Both speak MCP over streamable HTTP

2. Define your agent in a file named cagent.yml

agents:
  root:
    model: dmr/ai/gpt-oss
    description: This is an agent exposing Audit and Docs MCP tools for an Alfresco Repository.
    instruction: |
      You have two MCP backends:
      - AUDIT: retention/compliance/logs (tool names start with "audit__").
      - DOCS: content search/metadata/renditions/transforms (tool names start with "docs__").
      Routing rule:
      - If the request is about logs/audit/retention/compliance, use an AUDIT tool.
      - If it's search/metadata/renditions/transforms/content, use a DOCS tool.
      Process:
      - Based on the user request, select the most appropriate tool to call.
      - Use the tool with the correct parameters.
      - If the tool's response is sufficient, return it to the user.
      - If more information is needed, ask the user for clarification or use another tool.
      - Always aim to provide a complete and accurate response to the user.
      - If unsure about which tool to use, ask the user for more details.
      - Avoid using generic tools; always prefer specific ones.
      - If the user request is out of scope, politely decline.
      - If there is a communication error with a tool, don't dump the error to the user.
    inference_params:
      temperature: 0

    toolsets:
      - type: mcp
        remote:
          url: "http://localhost:8081/mcp"
          transport_type: streamable
      - type: mcp
        remote:
          url: "http://localhost:8003/mcp"
          transport_type: streamable

This cagent specification defines a root agent powered by Docker Model Runner using ChatGPT OSS ("dmr/ai/gpt-oss") that exposes two specialized MCP backends for an Alfresco Repository. The agent routes user requests by matching the topic (e.g., audit vs. content) to the appropriate MCP tools, ensuring precise tool selection, structured responses, and clarification when necessary.

3. Run cagent

First, install cagent from the Docker announcement page. Then:

cagent run cagent.yml --tui=false

You’re now talking to your Alfresco repository via an AI agent

4. Example dialogue

Here’s a real session showing how the agent automatically switches between Docs MCP and Audit MCP:

------- Welcome to cagent! -------

> Search for documents in Alfresco Repository that includes "budget"

--- Agent: root ---
🛠️ Tool call requires confirmation 🛠️
search_content(query: "budget")

Can I run this tool? ([y]es/[a]ll/[n]o): Yes 👍

search_content response → Found 6 item(s) matching the query...

Here are the documents that contain **“budget”**:
| Title | Node ID | Type | Created |
|-------|---------|------|---------|
| budget.xls | 5fa74ad3-9b5b-461b-9df5-de407f1f4fe7 | cm:content | 2011-02-15 |
| Meeting Notes 2011-02-10.doc | a8290263-4178-48f5-a0b0-be155a424828 | cm:content | 2011-02-24 |
...

> List Alfresco audit apps

get_audit_applications() → [tagging, search]

> List Alfresco audit entries for audit app "search"

get_audit_entries(appId: "search") → 10 entries including multiple `budget` queries

Notice how the same agent seamlessly switches between search and audit operations based on intent.

cagent in context

As introduced before, cagent is the fastest way to spin up Alfresco-aware agents: Docker-first, driven by a simple YAML spec, and already MCP-ready with little to no coding required.

By contrast, LangGraph can be used when you need complex, code-level agent workflows with deterministic graphs, custom state management, and non-trivial branching. LlamaIndex is less about orchestration and more about powering retrieval-augmented generation. It pairs well with cagent if you want richer document context feeding your agents.

Why this matters

Familiar workflow: Just like Docker Compose for services, but for agents
Extensible: Add more MCP backends (e.g., renditions, transforms, external APIs)
Reproducible: Share YAML + Compose and anyone can reproduce your setup
Future-proof: Docker is actively building an ecosystem around agents, including integration with Docker Desktop and Offload.

For Alfresco developers, this is a direct path to AI-powered content operations without reinventing orchestration logic.

Next steps

1. Try the full workflow: clone the repo, add the YAML, and run "cagent"
2. Experiment with more prompts
3. Share your feedback with Docker here
4. Think about how this pattern could streamline your own Alfresco projects.

Final thought: Just as Docker simplified containers, "cagent" is poised to simplify the agentic future. For Alfresco, it means we can run intelligent, tool-powered workflows with the same ease we run our repositories!