{"id":17568,"date":"2025-09-24T11:45:06","date_gmt":"2025-09-24T18:45:06","guid":{"rendered":"https:\/\/www.couchbase.com\/blog\/?p=17568"},"modified":"2025-09-24T11:45:06","modified_gmt":"2025-09-24T18:45:06","slug":"building-ai-agent-couchbase-cagent","status":"publish","type":"post","link":"https:\/\/www.couchbase.com\/blog\/es\/building-ai-agent-couchbase-cagent\/","title":{"rendered":"Building an AI Agent with Couchbase MCP and cagent"},"content":{"rendered":"

The AI landscape is rapidly transitioning from simple chatbots to AI agents that can plan, reason, and execute tasks autonomously. At the forefront is Docker cagent<\/em> \u2013 a powerful, easy-to-use, multi-agent runtime that’s democratizing AI agent development for developers worldwide.<\/p>\n

Unlike traditional AI chatbots that provide simple text based response, agentic AI systems built with cagent<\/a> can break down complex issues into manageable tasks, delegate work to specialized AI agents, while leveraging external tools and APIs through the Model Context Protocol (MCP).<\/p>\n

In this post, we\u2019ll walk through setting up an AI Agent that understands natural language queries, interact with a Couchbase instance to read\/write data, how to leverage the Couchbase MCP server<\/a> and how you can easily ship this agent to production using cagent.<\/p>\n

What is cagent?<\/h2>\n

cagent<\/em>\u00a0is an open-source, customizable multi-agent runtime by Docker that makes it simple to orchestrate AI agents with specialized tools and capabilities in order to manage interactions between them.<\/p>\n

Key features of cagent<\/h2>\n
    \n
  1. \n
      \n
    1. YAML configuration: Define your entire agent ecosystem using simple, declarative YAML files \u2013 no complex coding is required.<\/li>\n
    2. Built-in reasoning capabilities: tools like “think”, “todo”, and “memory” enable sophisticated problem-solving and context retention across sessions.<\/li>\n
    3. Support for multiple AI providers: Support for multiple AI providers like OpenAI, Anthropic, Google Gemini, and Docker Model Runner.<\/li>\n
    4. Rich ecosystem support: Agents can access external tools, APIs, and services through the\u00a0 Model Context Protocol (MCP).<\/li>\n<\/ol>\n<\/li>\n<\/ol>\n

      To learn how cagent works, you can refer to the official docs<\/a>El l\u00e9ame<\/a> y el uso<\/a> file. The concept is really easy to understand and the YAML structure defines everything limited to the required elements.<\/p>\n

       <\/p>\n

      Creating a Couchbase MCP AI agent with cagent<\/h2>\n

      Installing cagent<\/h3>\n

      First download cagent from the releases page of the project’s Repositorio GitHub<\/a>.<\/p>\n

      Once you’ve downloaded the appropriate binary for your platform, you may need to give it executable permissions. On macOS and Linux, this is done with the following command:<\/p>\n

      # linux amd64 build example\r\nchmod +x \/path\/to\/downloads\/cagent-linux-amd64\r\n<\/pre>\n
      You can then rename the binary to cagent and configure your SENDERO<\/em> to be able to find it.<\/p>\n
      Based on the models you configure your agents to use, you will need to set the corresponding provider API key accordingly, all theses keys are optional, you will likely need at least one of these:<\/p>\n
      # For OpenAI models\r\nexport OPENAI_API_KEY=your_api_key_here\r\n<\/pre>\n
      Creating a new agent<\/h3>\n
      Using the command: cagent new<\/p>\n
      You can quickly generate agents or multi-agent teams using a single prompt, using the command: cagent new<\/code>.<\/p>\n
      In this example, we will create a simple agent that understands natural language queries, interact with a Couchbase instance to retrieve or manipulate data, and provide meaningful responses using the Couchbase MCP Server. For the Couchbase MCP server we will use the Docker MCP Catalog<\/a>.<\/p>\n
      cagent new --model openai\/gpt-4.1 --max-tokens 32000<\/pre>\n
      We will add a prompt for our agent to leverage the Couchbase MCP server:\"\"<\/p>\n
      This generates YAML code and is saved in couchbase_agent.yaml<\/i>. This single agent (root) will serve as the entry point and leverages Couchbase server tools for all database-related tasks and queries.<\/p>\n
      version: \"2\"\r\nagents:\r\n\u00a0\u00a0root:\r\n\u00a0\u00a0\u00a0\u00a0model: openai\r\n\u00a0\u00a0\u00a0\u00a0description: Agent for answering questions, executing queries, and exploring data in your Couchbase database using the Docker MCP Couchbase server as a tool.\r\n\u00a0\u00a0\u00a0\u00a0instruction: |\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0You are an expert Couchbase database assistant. Your job is to answer user questions related to the Couchbase database, execute N1QL queries, summarize data, help with troubleshooting, or provide documentation-style answers as requested. Use the Couchbase MCP server to run queries and fetch schema\/data for better answers. If a user asks for query samples, data exploration, or troubleshooting, make sure to clarify the specific request if not clear, then use the tools as needed, and present results clearly and understandably.\r\n\u00a0\u00a0\u00a0\u00a0toolsets:\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0- type: mcp\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0ref: docker:couchbase\r\n\u00a0\u00a0\u00a0\u00a0add_date: true\r\n\u00a0\u00a0\u00a0\u00a0add_environment_info: false\r\n\r\nmodels:\r\n\u00a0\u00a0openai:\r\n\u00a0\u00a0\u00a0\u00a0provider: openai\r\n\u00a0\u00a0\u00a0\u00a0model: gpt-5-mini\r\n\u00a0\u00a0\u00a0\u00a0max_tokens: 64000\r\n<\/pre>\n
      Explicaci\u00f3n<\/h3>\n
      version: “2”<\/b><\/p>\n
      This specifies the configuration schema version<\/b> for cagent. Version 2 is the current stable spec.<\/p>\n
      agentes<\/b><\/p>\n
      This block defines the agents currently available. In this example we only define one.<\/p>\n