From eeaff732e790921e8d85aacddb994b5c0a37a5ec Mon Sep 17 00:00:00 2001 From: Nadine2016 Date: Tue, 18 Aug 2026 15:59:28 -0400 Subject: [PATCH 1/4] About section Signed-off-by: Nadine2016 --- assets/img/ar-oss-architecture.svg | 4 + content/docs/about.md | 80 ------------------ content/docs/about/_index.md | 5 ++ content/docs/about/about.md | 75 +++++++++++++++++ content/docs/about/architecture.md | 54 ++++++++++++ content/docs/about/concepts.md | 84 +++++++++++++++++++ content/docs/agents/_index.md | 2 +- content/docs/install/_index.md | 5 -- content/docs/mcp/_index.md | 2 +- content/docs/operations/database.md | 2 +- content/docs/prompts/_index.md | 2 +- content/docs/quickstart.md | 2 +- content/docs/setup/_index.md | 5 ++ content/docs/{install => setup}/docker.md | 3 +- content/docs/{install => setup}/kubernetes.md | 3 +- content/docs/setup/mcp-client.md | 84 +++++++++++++++++++ content/docs/skills/_index.md | 2 +- hugo_stats.json | 21 +++++ 18 files changed, 342 insertions(+), 93 deletions(-) create mode 100644 assets/img/ar-oss-architecture.svg delete mode 100644 content/docs/about.md create mode 100644 content/docs/about/_index.md create mode 100644 content/docs/about/about.md create mode 100644 content/docs/about/architecture.md create mode 100644 content/docs/about/concepts.md delete mode 100644 content/docs/install/_index.md create mode 100644 content/docs/setup/_index.md rename content/docs/{install => setup}/docker.md (90%) rename content/docs/{install => setup}/kubernetes.md (94%) create mode 100644 content/docs/setup/mcp-client.md diff --git a/assets/img/ar-oss-architecture.svg b/assets/img/ar-oss-architecture.svg new file mode 100644 index 0000000..3129b9b --- /dev/null +++ b/assets/img/ar-oss-architecture.svg @@ -0,0 +1,4 @@ + + +UI · CLI · REST APIRegistry server(install once)PostgreSQLkagent (Kubernetes)agentregistry3rd-party componentsRuntimesCLIENTSCONTROL PLANERUNTIMESPersist registry stateLocal (Docker) \ No newline at end of file diff --git a/content/docs/about.md b/content/docs/about.md deleted file mode 100644 index cd477d7..0000000 --- a/content/docs/about.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: About agentregistry -weight: 10 -description: "Learn what agentregistry is: an open source, centralized catalog for building, publishing, discovering, and governing AI artifacts across registries." ---- - -Agentregistry is an open source, centralized AI artifact catalog that helps you build, package, publish, discover, and govern AI artifacts—including agents, skills, MCP servers, and prompts—spread across multiple container registries and GitHub repositories. It provides a single source of truth for the AI building blocks your teams are allowed to share, deploy, and compose into applications. - -## Challenges with AI Artifacts - -As organizations build AI applications, they face significant challenges in discovering, managing, and governing AI artifacts across different environments and teams. These challenges apply broadly to all types of AI artifacts—agents, MCP servers, skills, prompts, and other AI components—regardless of the protocols or frameworks they use. - -### Discovery across environments - -One of the most pressing challenges is discovering which AI artifacts are available and where they can be found. AI artifacts are often scattered across multiple container registries, GitHub repositories, internal development environments, and third-party sources. This fragmentation makes it difficult for teams to: - -- **Find available artifacts**: Without a centralized catalog, developers struggle to discover what agents, MCP servers, skills, or prompts already exist and are approved for use. This leads to duplicate work and inconsistent implementations. - -- **Search and filter**: Without proper metadata and search capabilities, finding the right artifact for a specific use case becomes a time-consuming manual process. - -### Governance and approval - -Organizations need to ensure that only approved, secure, and validated AI artifacts are used in production environments. However, the current landscape lacks mechanisms for: - -- **Approval workflows and cross-environment governance**: There's no standardized way to review, approve, and control which artifacts are available to teams. With artifacts spread across multiple environments, repositories, and registries, enforcing consistent security policies, quality standards, and compliance requirements is difficult. - -- **Visibility into artifact status**: Teams often don't know which artifacts are approved for use. This lack of visibility can lead to security risks and compliance violations. - -- **Audit and compliance**: Maintaining audit trails that show who approved an artifact and when becomes crucial to meet legal and compliance requirements. - -### Artifact registry infrastructure - -The infrastructure for managing AI artifacts at scale is fragmented and incomplete: - -- **No standardized storage**: There's no unified way to store, version, and distribute AI artifacts across organizations and teams. Artifacts end up in different container registries, code repositories, or internal systems. - -- **Naming and resolution**: Without a centralized naming and resolution system, it's unclear how to resolve artifact names to their actual locations, versions, or deployment endpoints across different environments. - -- **Lifecycle management**: Managing the complete lifecycle of artifacts—from creation through deployment, updates, and deprecation—requires bundling together multiple tools and processes. - -- **Metadata enrichment**: While some artifacts have basic metadata, there's no systematic way to enrich artifacts with validation scores, security assessments, usage analytics, or other contextual information that helps teams make informed decisions. - -These challenges make it difficult for organizations to build production-ready AI applications where teams can confidently discover, deploy, and manage AI artifacts at scale. Without proper discovery and governance mechanisms, organizations risk security vulnerabilities, compliance issues, duplicated effort, and inconsistent implementations. - -## How agentregistry fills the gaps - -Learn how agentregistry allows you to overcome the challenge of managing AI artifacts across an organization. - -### Build, package, and deploy - -Agentregistry provides built-in tooling—both a CLI (`arctl`) and a web UI—to help developers manage the entire lifecycle of AI artifacts, including agents, MCP servers, skills, and prompts. - -With `arctl`, you can scaffold new artifacts from templates, build and package them as Docker images, run them locally to verify they work, and publish them to agentregistry with a single command. Once published, artifacts can be pulled from the registry and deployed to a developer's local machine or a Kubernetes cluster, without any complex deployment configuration. - -Skills and prompts have lightweight publishing options beyond Docker images: skills can be registered directly from a GitHub repository or a local folder, and prompts can be published as versioned text directly from the CLI. - -Before deploying agents to agentic platforms, developers can use agentregistry to compose agents by selecting specific MCP servers, skills, and prompts to attach. This composition approach lets developers assemble powerful, customized agents from proven, tested registry components rather than building everything from scratch. - -### Centralized governance and curation - -Agentregistry enables organizations to establish comprehensive governance, maintain security standards, and ensure quality across all AI artifacts used within the company. Organizations can collect AI artifacts from any source—developed internally, sourced from open-source repositories, or obtained from third-party vendors—into a single registry that the organization controls. This eliminates fragmentation and provides a single source of truth for all AI artifacts. - -You can implement review and approval workflows for artifacts before they become available to teams, ensuring that agents, servers, skills, and prompts meet security, quality, and compliance requirements. Only artifacts that are approved and published to agentregistry can be deployed into environments, preventing untested or potentially insecure artifacts from reaching production. - -Agentregistry also tracks and manages multiple versions of artifacts, allowing teams to use stable versions while new versions are being tested and approved. - -### Discovery - -Agentregistry makes it easy for developers to discover, pull, and share AI artifacts across the organization through both the web UI and the `arctl` CLI. Artifacts can be searched by name, description, tags, or metadata. Agentregistry also supports semantic search powered by vector embeddings, so developers can find relevant artifacts by describing what they need rather than knowing exact names. - -You can also track dependencies between artifacts—for example, which MCP servers or skills an agent depends on. - -### Client integration - -Once artifacts are in the registry, agentregistry can generate ready-to-use client configurations for popular AI development tools, including Claude Desktop, Cursor, and VS Code. This means developers can immediately start using approved MCP servers and agents in their local environments without manual configuration. Agentregistry also integrates with Agent Gateway to provide a unified MCP infrastructure access layer for teams deploying at scale. - -### Data enrichment - -Agentregistry automatically validates and scores ingested artifacts to provide deeper insights for both organizations and developers. When AI artifacts are imported from any source into agentregistry, the platform performs scoring and validation that enriches each artifact with contextual information—such as validation scores, security assessments, and metadata quality signals—helping teams make informed decisions about which artifacts to trust and deploy. - diff --git a/content/docs/about/_index.md b/content/docs/about/_index.md new file mode 100644 index 0000000..13afbe4 --- /dev/null +++ b/content/docs/about/_index.md @@ -0,0 +1,5 @@ +--- +title: About agentregistry +weight: 20 +description: +--- diff --git a/content/docs/about/about.md b/content/docs/about/about.md new file mode 100644 index 0000000..b1490f1 --- /dev/null +++ b/content/docs/about/about.md @@ -0,0 +1,75 @@ +--- +title: What is agentregistry? +weight: 10 +description: "Learn more about agentregisty." +--- + +Agentregistry is an open source, centralized AI artifact catalog that helps you build, package, publish, and discover AI artifacts, including agents, skills, MCP servers, prompts, and plugins that are spread across multiple container registries and GitHub repositories. It provides a single source of truth for the AI building blocks your teams are allowed to share, deploy, and compose into applications. + +## Challenges with AI Artifacts + +As development teams build AI applications, they face significant challenges in discovering and managing AI artifacts across different environments. These challenges apply broadly to all types of AI artifacts, regardless of the protocols or frameworks they use. + +### Tribal knowledge and informal sharing + +Without a registry, teams fall back on informal channels: MCP server endpoints shared in Slack, skill files passed over email, and word-of-mouth about which prompts work best. This tribal knowledge breaks down as teams grow: + +- Developers can't tell which artifacts exist or which are still actively maintained. +- A developer builds a useful skill and shares it with a colleague. When they iterate and improve it, the colleague is still running the old version, with no way to know that a newer version exists. +- MCP servers get stood up ad-hoc and shared informally. Over time, no one knows which are vetted by security, which are still running, or which expose sensitive capabilities. + +This kind of fragmentation leads to duplicated work, inconsistent implementations, and security blind spots. + +### Discovery across environments + +One of the most pressing challenges is discovering which AI artifacts are available and where they can be found. AI artifacts are often scattered across multiple container registries, GitHub repositories, internal development environments, and third-party sources. This fragmentation makes it difficult for teams to: + +- **Find available artifacts**: Without a centralized catalog, developers struggle to discover what agents, MCP servers, skills, or prompts already exist. This leads to duplicate work and inconsistent implementations. + +- **Search and filter**: Without proper metadata and search capabilities, finding the right artifact for a specific use case becomes a time-consuming manual process. + +### Skills and prompt version drift + +Skills and prompts evolve constantly. A developer iterates on a skill ten times, but everyone they originally shared it with is still on version one. There is no way to notify consumers that a newer version exists, no single place to publish the latest iteration, and no mechanism to ensure that agents built by different teams are using the same approved prompt baseline. + +### Artifact registry infrastructure + +The infrastructure for managing AI artifacts at scale is fragmented and incomplete: + +- **No standardized storage**: There's no unified way to store, version, and distribute AI artifacts across teams and registries. Artifacts end up in different container registries, code repositories, or personal machines. + +- **Naming and resolution**: Without a centralized naming and resolution system, it's unclear how to resolve artifact names to their actual locations, versions, or deployment endpoints across different environments. + +- **Lifecycle management**: Managing the complete lifecycle of artifacts, from creation through deployment, updates, and deprecation, requires bundling together multiple tools and processes. + +These challenges make it difficult for teams to confidently discover, deploy, and manage AI artifacts. Without proper discovery mechanisms, teams risk duplicated effort and inconsistent implementations. + +## How agentregistry fills the gaps + +Learn how agentregistry allows you to overcome the challenge of managing AI artifacts across your team. + +### Build, package, and deploy + +Agentregistry provides built-in tooling to help developers manage the entire lifecycle of AI artifacts, including agents, MCP servers, skills, prompts, and plugins. + +With the `arctl` CLI, you can scaffold new artifacts from templates, build and package them as Docker images, run them locally to verify they work, and publish them to agentregistry with a single command. Once published, artifacts can be pulled from the registry and deployed to a developer's local machine or a Kubernetes cluster, without any complex deployment configuration. + +Before deploying agents to agentic platforms, developers can use agentregistry to compose agents by selecting specific MCP servers, skills, and prompts to attach. This composition approach lets developers assemble powerful, customized agents from proven, tested registry components rather than building everything from scratch. + +### Centralized governance and curation + +Agentregistry helps teams maintain standards and ensure quality across all AI artifacts they use. Teams can collect AI artifacts from multiple sources—internally developed, sourced from open-source repositories, or obtained from third-party vendors—into a single registry. This eliminates fragmentation and provides a single source of truth for all AI artifacts. + +Agentregistry tracks and manages multiple versions of artifacts, allowing teams to use stable versions while new versions are being reviewed and updated. + +### Discovery + +Agentregistry makes it easy for developers to discover, pull, and share AI artifacts across the team through both the web UI and the `arctl` CLI. Artifacts can be searched by name, description, tags, or metadata. Agentregistry also supports semantic search powered by vector embeddings, so developers can find relevant artifacts by describing what they need rather than knowing exact names. + +You can also track dependencies between artifacts, such as MCP servers or skills that an agent depends on. + +## Next steps + +{{< cards >}} +{{< card link="/docs/about/concepts/" title="Core concepts" description="Understand the catalog, artifact types, runtimes, and management interfaces." >}} +{{< /cards >}} diff --git a/content/docs/about/architecture.md b/content/docs/about/architecture.md new file mode 100644 index 0000000..d9e56c9 --- /dev/null +++ b/content/docs/about/architecture.md @@ -0,0 +1,54 @@ +--- +title: Architecture +weight: 12 +description: "Review the components that make up agentregistry and the role that each one plays." +--- + +Agentregistry is a single control plane that you install once and connect to one or more runtimes. It provides a common catalog and control-plane experience across those runtimes, while deployment paths vary by runtime. + +## Component architecture + +The following diagram shows the components that make up agentregistry and how they relate to each other. + +{{< reuse-image src="img/ar-oss-architecture.svg" >}} + +### Registry server + +The registry server is the core of the control plane that manages the artifact catalog, deployments, and runtime connections. It serves the registry UI and the REST API that is used by the `arctl` CLI and other integrations. The server listens on port `12121` by default and exposes the registry as an MCP server on port `13131`. + +### PostgreSQL + +PostgreSQL is the control plane's system of record. It stores published AI artifacts and versions, deployments, runtime connections, and related metadata. + +By default, the Helm chart and Docker Compose file deploy a bundled PostgreSQL instance as a single pod or container for development and evaluation. For production, connect the registry to an external PostgreSQL database. For more information, see [BYO PostgreSQL database]({{< link path="/operations/database/" >}}). + +### Management interfaces + +You interact with the registry through three interfaces, all served by the registry server. + +| Interface | Description | +|---|---| +| **Registry UI** | A browser-based dashboard for browsing and searching the catalog, managing artifacts, and deploying agents and MCP servers. | +| **`arctl` CLI** | A command-line client for developers and automation. Use it to scaffold, build, publish, pull, and deploy artifacts, and to script the artifact lifecycle in CI/CD pipelines. | +| **REST API** | HTTP endpoints that expose the same capabilities as the UI and CLI. Use the API to integrate the registry into your own tools and portals. | + +## Runtimes + +A **runtime** is a platform that the control plane connects to in order to deploy agents and MCP servers, or discover existing agents. One registry can connect to multiple runtimes at the same time. + +### Docker (local) + +When you install agentregistry with Docker Compose, the Docker daemon on your local machine acts as the deployment target. The registry server runs alongside the bundled PostgreSQL container in the Compose stack. Agents and MCP servers are run as containers on the same Docker host. + +### Kubernetes + +When you install agentregistry in a Kubernetes cluster, the registry connects to [kagent](https://kagent.dev) to deploy and manage agents and MCP servers as Kubernetes workloads. The registry server runs as a Deployment in the `agentregistry` namespace and communicates with the kagent controller to materialize catalog entries as native Kubernetes resources. + + +## Next steps + +{{< cards >}} +{{< card link="/docs/concepts/" title="Core concepts" description="Understand the catalog, artifact types, runtimes, and management interfaces." >}} +{{< card link="/docs/setup/docker/" title="Install with Docker" description="Install agentregistry for local development with Docker." >}} +{{< card link="/docs/setup/kubernetes/" title="Install on Kubernetes" description="Install agentregistry in a Kubernetes cluster with Helm." >}} +{{< /cards >}} diff --git a/content/docs/about/concepts.md b/content/docs/about/concepts.md new file mode 100644 index 0000000..c47f3eb --- /dev/null +++ b/content/docs/about/concepts.md @@ -0,0 +1,84 @@ +--- +title: Core concepts +weight: 11 +description: "Understand the key concepts of agentregistry, including the artifact catalog, artifact types, runtimes, and management interfaces." +--- + +Agentregistry addresses the AI artifact management challenges that arise as development teams grow: artifacts scattered across environments, tribal knowledge about which agents exist, and version drift of AI artifacts. + +Review the following core concepts and what they cover in agentregistry. Then, dive deeper into each concept. + +| Concept | What it covers | +| -- | -- | +| [Catalog](#catalog) | A centralized, searchable inventory that replaces ad-hoc artifact sharing across Slack, email, and personal machines | +| [Artifacts](#artifacts) | The AI building blocks the catalog stores: agents, MCP servers, prompts, and skills | +| [Runtimes](#runtimes) | Agentic platforms the registry connects to for deployment, agent discovery, and MCP traffic governance | +| [Management interfaces](#management-interfaces) | The registry UI, `arctl` CLI, and REST API | + +## Catalog + +An **artifact catalog** is a centralized, searchable inventory of all AI building blocks your team uses, including agents, MCP servers, prompts, and skills. Think of it as a package registry for AI, similar to how Docker Hub or `npm` manage container images and code libraries, but designed for the lifecycle management challenges that are unique to AI systems. + +Without a catalog, teams end up with fragmented artifact sprawl. AI building blocks are scattered across GitHub repos, internal wikis, container registries, and personal machines. MCP server endpoints get shared over Slack and skill files get passed over email. When someone iterates on a skill, colleagues who received an earlier copy have no way of knowing whether a newer version exists. + +The agentregistry catalog solves this by giving every artifact a single authoritative home and making discovery straightforward. Developers publish artifacts to the catalog with a version tag. Any team member can then search artifacts by name, description, or tag to find what is available. + +## Artifacts + +The catalog stores different types of AI artifacts so that they can be consumed, deployed, maintained, and shared between different teams. Each type has its own lifecycle, versioning semantics, and deployment options. + +### Agents + +An **agent** is a deployable unit that you publish, version, and deploy to a runtime through the registry. When you add an agent to the catalog, other teams can discover it, reuse it, or compose it into multi-agent workflows. + +### MCP servers + +An **MCP server** exposes tools that agents can call at runtime. Agentregistry supports the full development lifecycle for MCP servers: scaffold a server, build and package it as a Docker image, publish it to the catalog, and deploy it to a local environment or a Kubernetes cluster. + +### Skills + +A **skill** is a reusable instruction set or slash command for AI agents that you can store as a versioned artifact in the catalog. Instead of sharing skill files ad-hoc, developers publish skills to the registry with a version tag. Consumers pull the latest version with a single `arctl pull` command. When the author iterates on a skill, they publish a new version to the catalog so that consumers can pull the update at any time. + +Skills can be registered directly from a GitHub or GitLab repository or a local folder. No Docker image is required. + +### Prompts + +A **prompt** is a versioned system prompt or instruction template stored in the catalog. Prompts let teams publish shared baselines—such as safety guardrails, agent persona guidelines, or reasoning frameworks that developers can reference from their agent configurations. Like other artifact types, prompts are versioned so consumers can always see which iteration they are using and when a newer version becomes available. + +### Plugins + +A **plugin** is a versioned bundle of agent capabilities, including skills, MCP server declarations, and lifecycle hooks that you publish to the catalog as a single unit. Plugins follow the same packaging format that coding harnesses like [Claude Code](https://code.claude.com/docs/en/plugins) use to distribute and install reusable agent extensions. + +> [!NOTE] +> Plugin management is available through the REST API and `arctl` CLI. A UI for plugins is not yet available in the open source release. + +## Runtimes + +A **runtime** is a platform where agentregistry deploys and manages agents and MCP servers. + +| Runtime | Description | +|---|---| +| **Docker** | Run agents and MCP servers on your local machine or a VM by using Docker Compose. This is the default runtime for local development. | +| **Kubernetes** | Deploy agents and MCP servers to a Kubernetes cluster by using the [kagent open source project](https://kagent.dev). This is the recommended runtime for shared team environments. | + +## Management interfaces + +Agentregistry exposes three interfaces for interacting with the registry. Each is suited to different personas and workflows. + +### Registry UI + +The registry UI is a browser-based dashboard for browsing and searching the catalog, managing artifacts, and deploying agents and MCP servers. It is served by the registry server on port `12121` by default. + +### `arctl` CLI + +`arctl` is the command-line interface for developers and operators who prefer scripting or terminal-based workflows. It covers the full artifact lifecycle, from scaffolding and publishing to querying the catalog and managing deployments. The CLI is the right choice for CI/CD pipelines, automated testing, and day-to-day developer tasks. + +### REST API + +The REST API exposes the full capabilities of the registry as HTTP endpoints, making it the right interface for automation engineers and teams that need to integrate the registry into custom tooling. Any action available in the UI or CLI is also available through the API. + +## Next steps + +{{< cards >}} +{{< card link="/docs/about/architecture/" title="Architecture" description="Review the components that make up agentregistry and the role that each one plays." >}} +{{< /cards >}} diff --git a/content/docs/agents/_index.md b/content/docs/agents/_index.md index 05937d4..2ba781d 100644 --- a/content/docs/agents/_index.md +++ b/content/docs/agents/_index.md @@ -1,5 +1,5 @@ --- title: Agents -weight: 20 +weight: 40 description: "Build, run, publish, and deploy AI agents with agentregistry." --- diff --git a/content/docs/install/_index.md b/content/docs/install/_index.md deleted file mode 100644 index f7c5a78..0000000 --- a/content/docs/install/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Install -weight: 15 -description: "Install agentregistry for local development or in a Kubernetes cluster." ---- \ No newline at end of file diff --git a/content/docs/mcp/_index.md b/content/docs/mcp/_index.md index 322adc2..dd99667 100644 --- a/content/docs/mcp/_index.md +++ b/content/docs/mcp/_index.md @@ -1,5 +1,5 @@ --- title: MCP -weight: 30 +weight: 50 description: "Build, run, publish, and deploy Model Context Protocol (MCP) servers with agentregistry." --- diff --git a/content/docs/operations/database.md b/content/docs/operations/database.md index a9ec132..7975efb 100644 --- a/content/docs/operations/database.md +++ b/content/docs/operations/database.md @@ -11,7 +11,7 @@ For production environments, replace the bundled database with an external Postg ## Before you begin - Creata or use an existing external PostgreSQL instance (version 14 or later) that is reachable from your agentregistry installation. For example, you can create an [Amazon RDS instance](https://aws.amazon.com/rds/resources/) -- Install agentregistry on [Docker]({{< link path="/install/docker" >}}) or [Kubernetes]({{< link path="/install/kubernetes" >}}) guide. +- Install agentregistry on [Docker]({{< link path="/setup/docker" >}}) or [Kubernetes]({{< link path="/setup/kubernetes" >}}) guide. ## Step 1: Create the agentregistry database diff --git a/content/docs/prompts/_index.md b/content/docs/prompts/_index.md index 9da4570..f23075c 100644 --- a/content/docs/prompts/_index.md +++ b/content/docs/prompts/_index.md @@ -1,5 +1,5 @@ --- title: Prompts -weight: 45 +weight: 60 description: "Create, publish, and manage reusable prompts with agentregistry." --- diff --git a/content/docs/quickstart.md b/content/docs/quickstart.md index 0db44ae..1d3968f 100644 --- a/content/docs/quickstart.md +++ b/content/docs/quickstart.md @@ -12,7 +12,7 @@ Want to learn more about agentregistry? Check out the [About](/docs/about/) sect In this guide, you learn how to install agentregistry for local development with Docker. This approach is useful if you want to run agentregistry from your local machine, an on-prem environment, or a VM. Agentregistry is spun up by using Docker containers and you can use this installation to deploy AI artifacts to your local environment and Kubernetes clusters. -To install agentregistry in a Kubernetes cluster instead, see the [Install in Kubernetes](/docs/install/kubernetes/) guide. +To install agentregistry in a Kubernetes cluster instead, see the [Install in Kubernetes](/docs/setup/kubernetes/) guide. ## Before you begin diff --git a/content/docs/setup/_index.md b/content/docs/setup/_index.md new file mode 100644 index 0000000..dad7e6c --- /dev/null +++ b/content/docs/setup/_index.md @@ -0,0 +1,5 @@ +--- +title: Setup +weight: 30 +description: "Install agentregistry for local development or in a Kubernetes cluster, and connect your AI development tools." +--- \ No newline at end of file diff --git a/content/docs/install/docker.md b/content/docs/setup/docker.md similarity index 90% rename from content/docs/install/docker.md rename to content/docs/setup/docker.md index 31af808..c1fa0a8 100644 --- a/content/docs/install/docker.md +++ b/content/docs/setup/docker.md @@ -6,7 +6,7 @@ description: "Install agentregistry for local development with Docker to build, Use this guide to install agentregistry for local development with Docker. This approach is useful if you want to run agentregistry from your local machine, an on-prem environment, or a VM. Agentregistry is spun up using Docker containers and you can use this installation to build, publish, and deploy AI artifacts to your local environment and Kubernetes clusters. -To install agentregistry in a Kubernetes cluster instead, see the [Install in Kubernetes](/docs/install/kubernetes/) guide. +To install agentregistry in a Kubernetes cluster instead, see the [Install in Kubernetes](/docs/setup/kubernetes/) guide. ## Before you begin @@ -29,3 +29,4 @@ With agentregistry up and running, you can explore how to build, publish, and de * [**Skills**](/docs/skills/): Build and publish skills that you can add to your agents. * [**Prompts**](/docs/prompts/): Build and publish prompts that you can add to your agents. * [**BYO PostgreSQL database**]({{< link path="/operations/database/" >}}): Replace the bundled PostgreSQL instance with an external database for production use. +* [**Connect AI development tools**]({{< link path="/setup/mcp-client/" >}}): Connect Claude Code, Cursor, VS Code, or Kiro to the registry catalog. diff --git a/content/docs/install/kubernetes.md b/content/docs/setup/kubernetes.md similarity index 94% rename from content/docs/install/kubernetes.md rename to content/docs/setup/kubernetes.md index 992ceab..e6ed107 100644 --- a/content/docs/install/kubernetes.md +++ b/content/docs/setup/kubernetes.md @@ -7,7 +7,7 @@ description: "Install agentregistry in a Kubernetes cluster with Helm for shared Use this guide to install agentregistry in a Kubernetes cluster by using Helm. This approach is useful for team environments where multiple developers need shared access to a central artifact registry. > [!NOTE] -> If you install agentregistry in a Kubernetes cluster, you cannot deploy AI artifacts to a local environment. To deploy them to a local environment, you must [install agentregistry locally with Docker](/docs/install/docker/). +> If you install agentregistry in a Kubernetes cluster, you cannot deploy AI artifacts to a local environment. To deploy them to a local environment, you must [install agentregistry locally with Docker](/docs/setup/docker/). ## Before you begin @@ -74,3 +74,4 @@ With agentregistry up and running, you can explore how to build, publish, and de * [**MCP servers**](/docs/mcp/): Create and run MCP tool servers, add tools, and publish them as Docker images. * [**Skills**](/docs/skills/): Build and publish skills that you can add to your agents. * [**Prompts**](/docs/prompts/): Build and publish prompts that you can add to your agents. +* [**Connect AI development tools**]({{< link path="/setup/mcp-client/" >}}): Connect Claude Code, Cursor, VS Code, or Kiro to the registry catalog. diff --git a/content/docs/setup/mcp-client.md b/content/docs/setup/mcp-client.md new file mode 100644 index 0000000..6812293 --- /dev/null +++ b/content/docs/setup/mcp-client.md @@ -0,0 +1,84 @@ +--- +title: Connect AI development tools +weight: 30 +description: "Connect Claude Code, Cursor, VS Code, or Kiro to agentregistry so your AI development tools can discover and use catalog artifacts." +--- + +Agentregistry runs its own MCP server that exposes the artifact catalog as MCP tools. By connecting your AI development tools to this server, you can query the registry from inside your IDE or coding assistant without leaving your workflow. + +Once connected, your AI development tool can call tools such as `list_agents`, `get_agent`, `list_servers`, `get_server`, `list_skills`, `get_skill`, `list_prompts`, and `get_prompt` to browse and fetch catalog artifacts. + +## Supported clients + +| Client | Command | +|---|---| +| [Claude Code](https://code.claude.ai) | `arctl configure claude-code` | +| [Cursor](https://www.cursor.com) | `arctl configure cursor` | +| [VS Code](https://code.visualstudio.com) | `arctl configure vscode` | +| [Kiro](https://kiro.dev) | `arctl configure kiro` | + +## Before you begin + +- Install agentregistry on [Docker]({{< link path="/setup/docker" >}}) or [Kubernetes]({{< link path="/setup/kubernetes" >}}). +- Install the `arctl` CLI. See [Install with Docker]({{< link path="/setup/docker" >}}) or [Install on Kubernetes]({{< link path="/setup/kubernetes" >}}) for the install steps. +- Make sure agentregistry is running and accessible at `http://localhost:12121`. + +## Configure a client + +Run `arctl configure` with the name of your client. The command writes the MCP server configuration to the correct location for that client automatically. + +```sh +arctl configure +``` + +For example, to configure Claude Code: + +```sh +arctl configure claude-code +``` + +Example output: + +```console +Configured Claude Code +``` + +By default, the registry MCP server runs on port `21212`. To use a different port or a custom URL, pass `--port` or `--url`: + +```sh +arctl configure claude-code --port 21212 +arctl configure claude-code --url http://my-registry-host:21212/mcp +``` + +## Verify the connection + +After configuring a client, restart it and check that `agentregistry-mcp` appears in the list of connected MCP servers. You can then ask your AI tool to list available agents or MCP servers from the registry. + +For example, in Claude Code you can type: + +``` +What agents are available in the agentregistry catalog? +``` + +Claude Code calls the `list_agents` tool and returns a list of published agents from your catalog. + +## Available tools + +The registry MCP server exposes the following tools for querying the catalog. + +| Tool | Description | +|---|---| +| `list_agents` | List published agents with optional name and tag filters. | +| `get_agent` | Fetch a published agent by name and tag. | +| `list_servers` | List published MCP servers with optional name and tag filters. | +| `get_server` | Fetch a published MCP server by name and tag. | +| `list_skills` | List published skills with optional name and tag filters. | +| `get_skill` | Fetch a published skill by name and tag. | +| `list_prompts` | List published prompts with optional name and tag filters. | +| `get_prompt` | Fetch a published prompt by name and tag. | +| `list_plugins` | List published plugins with optional name and tag filters. | +| `get_plugin` | Fetch a published plugin by name and tag. | +| `list_deployments` | List active deployments with optional name filter. | +| `get_deployment` | Fetch a deployment by name. | +| `list_runtimes` | List connected runtimes with optional name filter. | +| `get_runtime` | Fetch a runtime by name. | diff --git a/content/docs/skills/_index.md b/content/docs/skills/_index.md index 04c903d..b1f0e09 100644 --- a/content/docs/skills/_index.md +++ b/content/docs/skills/_index.md @@ -1,5 +1,5 @@ --- title: Skills -weight: 40 +weight: 60 description: "Build, publish, pull, and manage agentic skills with agentregistry." --- diff --git a/hugo_stats.json b/hugo_stats.json index 23ad9bc..513a853 100644 --- a/hugo_stats.json +++ b/hugo_stats.json @@ -547,9 +547,13 @@ "add-a-skill", "add-mcp-server", "add-tools", + "agent-deployment-sprawl", "agents", "ar-orbit", + "arctl-cli", "artifact-registry-infrastructure", + "artifacts", + "available-tools", "backToTop", "bash", "bb-panel", @@ -566,6 +570,9 @@ "cleanup", "client-integration", "command-specific-flags", + "component-architecture", + "components", + "configure-a-client", "content", "create-a-prompt", "create-a-skill", @@ -582,10 +589,12 @@ "deploy-the-agent", "deploy-the-mcp-server", "deployed-view", + "deployment-model", "disclosures", "discovery", "discovery-across-environments", "docker", + "docker-local", "evaluation", "example", "explore-the-ui", @@ -605,6 +614,8 @@ "install-with-helm", "kubernetes", "learn-more", + "management-interfaces", + "mcp-servers", "mobile-icons-menu", "mobile-icons-toggle", "next", @@ -613,6 +624,8 @@ "option-2-publish-from-a-github-repository-with-local-folder", "option-3-direct-registration-with-github-no-local-files-needed", "option-4-direct-registration-with-docker-image-no-local-files-needed", + "plugins", + "postgresql", "powershell", "preview-appbar", "prompts", @@ -623,18 +636,24 @@ "publish-the-skill", "pull-a-skill", "quickstart", + "registry-server", + "registry-ui", "remediation", "reports", + "rest-api", "run-the-agent", "run-the-mcp-server", + "runtimes", "servers", "setup", "skills", + "skills-and-prompt-version-drift", "solo-back-to-top", "specify-a-version", "step-1-create-the-agentregistry-database", "step-2-configure-agentregistry", "sub-commands", + "supported-clients", "tabs-panel-tabs-00-0", "tabs-panel-tabs-00-1", "tabs-panel-tabs-02-0", @@ -655,8 +674,10 @@ "terminal-body", "the-skillmd-file", "theme-toggle", + "tribal-knowledge-and-informal-sharing", "updates-and-questions", "usage", + "verify-the-connection", "verify-the-published-skill", "zsh" ] From 1c30d16ec82106b3563aaba10419e7ab843799c8 Mon Sep 17 00:00:00 2001 From: Nadine2016 Date: Tue, 18 Aug 2026 16:53:20 -0400 Subject: [PATCH 2/4] Registry as MCP Signed-off-by: Nadine2016 --- content/docs/setup/kubernetes.md | 7 +- content/docs/setup/mcp-client.md | 125 ++++++++++++++++++------------- hugo_stats.json | 8 +- 3 files changed, 79 insertions(+), 61 deletions(-) diff --git a/content/docs/setup/kubernetes.md b/content/docs/setup/kubernetes.md index e6ed107..98058fb 100644 --- a/content/docs/setup/kubernetes.md +++ b/content/docs/setup/kubernetes.md @@ -47,7 +47,12 @@ The Helm chart includes a bundled PostgreSQL instance for development and evalua kubectl port-forward -n agentregistry svc/agentregistry 12121:12121 ``` -4. [Open the agentregistry UI](http://localhost:12121/) in your browser. +4. Optional: If you want to connect AI development tools to the registry MCP server, port-forward the MCP port in a separate terminal. + ```sh + kubectl port-forward -n agentregistry svc/agentregistry 31313:31313 + ``` + +5. [Open the agentregistry UI](http://localhost:12121/) in your browser. ### Install the `arctl` CLI diff --git a/content/docs/setup/mcp-client.md b/content/docs/setup/mcp-client.md index 6812293..7ef1659 100644 --- a/content/docs/setup/mcp-client.md +++ b/content/docs/setup/mcp-client.md @@ -1,84 +1,101 @@ --- -title: Connect AI development tools +title: Connect AI clients to the registry MCP server weight: 30 description: "Connect Claude Code, Cursor, VS Code, or Kiro to agentregistry so your AI development tools can discover and use catalog artifacts." --- -Agentregistry runs its own MCP server that exposes the artifact catalog as MCP tools. By connecting your AI development tools to this server, you can query the registry from inside your IDE or coding assistant without leaving your workflow. +Agentregistry runs its own MCP server that exposes the artifact catalog as MCP tools on port `31313`. By connecting your AI development tools to this server, you can query the registry from inside your IDE or coding assistant without leaving your workflow. The MCP server reads directly from the registry database. -Once connected, your AI development tool can call tools such as `list_agents`, `get_agent`, `list_servers`, `get_server`, `list_skills`, `get_skill`, `list_prompts`, and `get_prompt` to browse and fetch catalog artifacts. +> [!NOTE] +> The MCP server is read-only. It does not invoke tools on cataloged MCP servers or proxy traffic to them. To add or update registry catalog items, you must continue using the UI, REST API, or `arctl` command line tool. + +## Supported tools + +After you connect to the MCP server, your AI development client can call the following tools to browse and fetch catalog artifacts. + +| Tool | Description | +| --- | --- | +| `list_agents`, `get_agent` | List or retrieve agents from the catalog. | +| `list_servers`, `get_server` | List or retrieve MCP servers from the catalog. | +| `list_skills`, `get_skill` | List or retrieve skills from the catalog. | +| `list_prompts`, `get_prompt` | List or retrieve prompts from the catalog. | +| `list_models`, `get_model` | List or retrieve models from the catalog. | +| `list_plugins`, `get_plugin` | List or retrieve plugins from the catalog. | +| `list_deployments`, `get_deployment` | List or retrieve deployments. | +| `list_runtimes`, `get_runtime` | List or retrieve connected runtimes. | +| `registry_health` | Check the health of the registry MCP server. | +| `registry_version` | Get build information for the registry. | ## Supported clients +The following MCP clients are supported out of the box. + | Client | Command | -|---|---| -| [Claude Code](https://code.claude.ai) | `arctl configure claude-code` | -| [Cursor](https://www.cursor.com) | `arctl configure cursor` | -| [VS Code](https://code.visualstudio.com) | `arctl configure vscode` | -| [Kiro](https://kiro.dev) | `arctl configure kiro` | +| --- | --- | +| [Claude Code](https://code.claude.ai) | `arctl configure claude-code --port 31313` | +| [Cursor](https://www.cursor.com) | `arctl configure cursor --port 31313` | +| [VS Code](https://code.visualstudio.com) | `arctl configure vscode --port 31313` | +| [Kiro](https://kiro.dev) | `arctl configure kiro --port 31313` | ## Before you begin -- Install agentregistry on [Docker]({{< link path="/setup/docker" >}}) or [Kubernetes]({{< link path="/setup/kubernetes" >}}). -- Install the `arctl` CLI. See [Install with Docker]({{< link path="/setup/docker" >}}) or [Install on Kubernetes]({{< link path="/setup/kubernetes" >}}) for the install steps. -- Make sure agentregistry is running and accessible at `http://localhost:12121`. +Install agentregistry on [Docker]({{< link path="/setup/docker" >}}) or [Kubernetes]({{< link path="/setup/kubernetes" >}}). -## Configure a client +## Connect to the MCP server -Run `arctl configure` with the name of your client. The command writes the MCP server configuration to the correct location for that client automatically. +1. From your project root, run the `arctl configure` command to configure your MCP client. The command writes a `.mcp.json` file to the current directory, which scopes the MCP server to that project. The following example uses Claude Code. To use a different client, update the command accordingly. For available options, see [Supported clients](#supported-clients). -```sh -arctl configure -``` + ```sh + arctl configure claude-code --port 31313 + ``` -For example, to configure Claude Code: + Example output: -```sh -arctl configure claude-code -``` + ```console + Configured Claude Code + ``` -Example output: +2. Open the Claude CLI. Verify that Claude wants to add the `arctl` MCP server. + ```sh + claude + ``` -```console -Configured Claude Code -``` + Example output: + ```console + New MCP server found in this project: arctl -By default, the registry MCP server runs on port `21212`. To use a different port or a custom URL, pass `--port` or `--url`: + MCP servers may execute code or access system resources. All tool calls require approval. Learn more in the MCP documentation. -```sh -arctl configure claude-code --port 21212 -arctl configure claude-code --url http://my-registry-host:21212/mcp -``` + ❯ 1. Use this MCP server + 2. Use this and all future MCP servers in this project + 3. Continue without using this MCP server + ``` -## Verify the connection +3. List the MCP servers that you have access to and verify that the `arctl` MCP server is listed. + ```sh + /mcp + ``` -After configuring a client, restart it and check that `agentregistry-mcp` appears in the list of connected MCP servers. You can then ask your AI tool to list available agents or MCP servers from the registry. + Example output: + ```console + Manage MCP servers + 1 server -For example, in Claude Code you can type: + Project MCPs (/path/to/your-project/.mcp.json) + ❯ arctl · ✔ connected · 18 tools + ``` -``` -What agents are available in the agentregistry catalog? -``` +4. Verify that you can access the server by prompting it. For example, you can ask it what agentregistry version you have. + ```sh + use the registry_version tool to tell me the agentregistry version + ``` -Claude Code calls the `list_agents` tool and returns a list of published agents from your catalog. + Example output: + ```console + Called arctl (ctrl+o to expand) + + ⏺ The registry (via agentregistry-mcp) reports v0.4.0. + ``` -## Available tools -The registry MCP server exposes the following tools for querying the catalog. -| Tool | Description | -|---|---| -| `list_agents` | List published agents with optional name and tag filters. | -| `get_agent` | Fetch a published agent by name and tag. | -| `list_servers` | List published MCP servers with optional name and tag filters. | -| `get_server` | Fetch a published MCP server by name and tag. | -| `list_skills` | List published skills with optional name and tag filters. | -| `get_skill` | Fetch a published skill by name and tag. | -| `list_prompts` | List published prompts with optional name and tag filters. | -| `get_prompt` | Fetch a published prompt by name and tag. | -| `list_plugins` | List published plugins with optional name and tag filters. | -| `get_plugin` | Fetch a published plugin by name and tag. | -| `list_deployments` | List active deployments with optional name filter. | -| `get_deployment` | Fetch a deployment by name. | -| `list_runtimes` | List connected runtimes with optional name filter. | -| `get_runtime` | Fetch a runtime by name. | diff --git a/hugo_stats.json b/hugo_stats.json index 513a853..d690caf 100644 --- a/hugo_stats.json +++ b/hugo_stats.json @@ -547,7 +547,6 @@ "add-a-skill", "add-mcp-server", "add-tools", - "agent-deployment-sprawl", "agents", "ar-orbit", "arctl-cli", @@ -568,17 +567,15 @@ "centralized-governance-and-curation", "challenges-with-ai-artifacts", "cleanup", - "client-integration", "command-specific-flags", "component-architecture", - "components", "configure-a-client", + "connect-to-the-mcp-server", "content", "create-a-prompt", "create-a-skill", "create-an-agent", "create-an-mcp-server", - "data-enrichment", "db-migrate-down", "db-migrate-force", "db-migrate-goto", @@ -589,7 +586,6 @@ "deploy-the-agent", "deploy-the-mcp-server", "deployed-view", - "deployment-model", "disclosures", "discovery", "discovery-across-environments", @@ -606,7 +602,6 @@ "gateway", "get-started", "global-flags", - "governance-and-approval", "how-agentregistry-fills-the-gaps", "how-it-works", "install", @@ -654,6 +649,7 @@ "step-2-configure-agentregistry", "sub-commands", "supported-clients", + "supported-tools", "tabs-panel-tabs-00-0", "tabs-panel-tabs-00-1", "tabs-panel-tabs-02-0", From 07f26caac28480565e4239525e72f19162809767 Mon Sep 17 00:00:00 2001 From: Nadine2016 Date: Wed, 19 Aug 2026 17:41:12 -0400 Subject: [PATCH 3/4] Rm local deployment target and Docker install, revise artifacts Signed-off-by: Nadine2016 --- assets/ar-docs/arctl.md | 14 ++ assets/ar-docs/kubernetes.md | 37 ++++ assets/img/ar-mcp-dark.svg | 4 + assets/img/ar-mcp-sum-dark.svg | 4 + assets/img/ar-mcp-sum.svg | 4 + assets/img/ar-mcp.svg | 4 + assets/img/ar-oss-architecture-dark.svg | 4 + assets/img/ar-oss-architecture.svg | 4 +- assets/img/ar-publish-skill-dark.svg | 4 + assets/img/ar-publish-skill.svg | 4 + assets/img/kagent-servers-dark.svg | 4 + assets/img/kagent-servers.svg | 4 + assets/img/mcp-connect-dark.svg | 4 + assets/img/mcp-connect.svg | 4 + assets/img/mcp-greeting-dark.svg | 4 + assets/img/mcp-greeting.svg | 4 + content/docs/about/about.md | 2 +- content/docs/about/architecture.md | 9 +- content/docs/about/concepts.md | 5 +- content/docs/agents/create.md | 85 ++++----- content/docs/agents/deploy/kubernetes.md | 20 +-- content/docs/agents/deploy/local.md | 105 ------------ content/docs/agents/mcp.md | 4 +- content/docs/agents/publish.md | 73 +++----- content/docs/agents/skills.md | 2 +- content/docs/mcp/create.md | 100 ----------- content/docs/mcp/deploy/_index.md | 5 - content/docs/mcp/deploy/kubernetes.md | 109 ------------ content/docs/mcp/deploy/local.md | 116 ------------- content/docs/mcp/local/_index.md | 5 + content/docs/mcp/local/create.md | 91 ++++++++++ content/docs/mcp/local/deploy/_index.md | 5 + content/docs/mcp/local/deploy/kagent.md | 157 +++++++++++++++++ content/docs/mcp/local/publish.md | 134 +++++++++++++++ content/docs/mcp/local/tools.md | 61 +++++++ content/docs/mcp/publish.md | 102 ----------- content/docs/mcp/remote.md | 70 ++++++++ content/docs/mcp/tools.md | 99 ----------- content/docs/operations/database.md | 69 +------- content/docs/plugins/_index.txt | 5 + content/docs/plugins/marketplace.txt | 84 +++++++++ content/docs/plugins/publish.txt | 98 +++++++++++ content/docs/prompts/publish.md | 146 ++++++---------- content/docs/quickstart.md | 43 ++--- content/docs/setup/docker.md | 32 ---- content/docs/setup/kubernetes.md | 56 +----- content/docs/setup/mcp-client.md | 2 +- content/docs/setup/runtime.md | 64 +++++++ content/docs/skills/create.md | 68 -------- content/docs/skills/publish.md | 209 +++++++++++++---------- content/docs/skills/pull.md | 57 ++----- content/docs/ui.md | 2 +- hugo_stats.json | 58 +++---- 53 files changed, 1195 insertions(+), 1264 deletions(-) create mode 100644 assets/ar-docs/arctl.md create mode 100644 assets/ar-docs/kubernetes.md create mode 100644 assets/img/ar-mcp-dark.svg create mode 100644 assets/img/ar-mcp-sum-dark.svg create mode 100644 assets/img/ar-mcp-sum.svg create mode 100644 assets/img/ar-mcp.svg create mode 100644 assets/img/ar-oss-architecture-dark.svg create mode 100644 assets/img/ar-publish-skill-dark.svg create mode 100644 assets/img/ar-publish-skill.svg create mode 100644 assets/img/kagent-servers-dark.svg create mode 100644 assets/img/kagent-servers.svg create mode 100644 assets/img/mcp-connect-dark.svg create mode 100644 assets/img/mcp-connect.svg create mode 100644 assets/img/mcp-greeting-dark.svg create mode 100644 assets/img/mcp-greeting.svg delete mode 100644 content/docs/agents/deploy/local.md delete mode 100644 content/docs/mcp/create.md delete mode 100644 content/docs/mcp/deploy/_index.md delete mode 100644 content/docs/mcp/deploy/kubernetes.md delete mode 100644 content/docs/mcp/deploy/local.md create mode 100644 content/docs/mcp/local/_index.md create mode 100644 content/docs/mcp/local/create.md create mode 100644 content/docs/mcp/local/deploy/_index.md create mode 100644 content/docs/mcp/local/deploy/kagent.md create mode 100644 content/docs/mcp/local/publish.md create mode 100644 content/docs/mcp/local/tools.md delete mode 100644 content/docs/mcp/publish.md create mode 100644 content/docs/mcp/remote.md delete mode 100644 content/docs/mcp/tools.md create mode 100644 content/docs/plugins/_index.txt create mode 100644 content/docs/plugins/marketplace.txt create mode 100644 content/docs/plugins/publish.txt delete mode 100644 content/docs/setup/docker.md create mode 100644 content/docs/setup/runtime.md delete mode 100644 content/docs/skills/create.md diff --git a/assets/ar-docs/arctl.md b/assets/ar-docs/arctl.md new file mode 100644 index 0000000..15aca32 --- /dev/null +++ b/assets/ar-docs/arctl.md @@ -0,0 +1,14 @@ +1. Install the `arctl` binary on your local machine to manage agentregistry resources. + ```sh + curl -fsSL https://raw.githubusercontent.com/agentregistry-dev/agentregistry/main/scripts/get-arctl | bash + + export PATH="/usr/local/bin:$PATH" + ``` + +2. Verify that the CLI is installed correctly. + ```sh + arctl version + ``` + +> [!TIP] +> By default, `arctl` connects to `http://localhost:12121`. If your agentregistry instance is exposed at a different address, set the `ARCTL_API_BASE_URL` environment variable or pass `--registry-url` on each command. For example: `export ARCTL_API_BASE_URL=http://:12121`. \ No newline at end of file diff --git a/assets/ar-docs/kubernetes.md b/assets/ar-docs/kubernetes.md new file mode 100644 index 0000000..9e3c201 --- /dev/null +++ b/assets/ar-docs/kubernetes.md @@ -0,0 +1,37 @@ +The agentregistry Helm chart includes a bundled PostgreSQL instance for development and evaluation. For production, [bring your own PostgreSQL instance]({{< link path="/operations/database/" >}}) instead. + +1. Install agentregistry with the bundled PostgreSQL instance. + ```sh + helm upgrade -i agentregistry oci://ghcr.io/agentregistry-dev/agentregistry/charts/agentregistry \ + --namespace agentregistry \ + --create-namespace + ``` + + > [!NOTE] + > The bundled PostgreSQL instance is for development and evaluation only. Data is lost if the PostgreSQL pod is restarted or rescheduled. For production, [use an external PostgreSQL instance]({{< link path="/operations/database/" >}}) instead. + +2. Verify that the agentregistry and PostgreSQL pods are up and running. + ```sh + kubectl get pods -n agentregistry + ``` + + Example output: + ```console + NAME READY STATUS RESTARTS AGE + agentregistry-c46b8bd98-hvnzf 1/1 Running 0 45s + agentregistry-postgresql-9858cbcbf-tk7p9 1/1 Running 0 45s + ``` + +3. Port-forward the agentregistry service to access the UI and API from your local machine. + ```sh + kubectl port-forward -n agentregistry svc/agentregistry 12121:12121 + ``` + +4. Optional: To connect AI development tools to the registry MCP server, port-forward the MCP port in a separate terminal. For more information, see [Connect AI clients to the registry MCP server]({{< link path="/setup/mcp-client/" >}}). + ```sh + kubectl port-forward -n agentregistry svc/agentregistry 31313:31313 + ``` + +5. [Open the agentregistry UI](http://localhost:12121/) in your browser. + + {{< reuse-image src="img/ar-local.svg" srcDark="img/ar-local-dark.svg" >}} \ No newline at end of file diff --git a/assets/img/ar-mcp-dark.svg b/assets/img/ar-mcp-dark.svg new file mode 100644 index 0000000..6934b6e --- /dev/null +++ b/assets/img/ar-mcp-dark.svg @@ -0,0 +1,4 @@ + + + \ No newline at end of file diff --git a/assets/img/ar-mcp-sum-dark.svg b/assets/img/ar-mcp-sum-dark.svg new file mode 100644 index 0000000..16b78fe --- /dev/null +++ b/assets/img/ar-mcp-sum-dark.svg @@ -0,0 +1,4 @@ + + + \ No newline at end of file diff --git a/assets/img/ar-mcp-sum.svg b/assets/img/ar-mcp-sum.svg new file mode 100644 index 0000000..942bb3a --- /dev/null +++ b/assets/img/ar-mcp-sum.svg @@ -0,0 +1,4 @@ + + + \ No newline at end of file diff --git a/assets/img/ar-mcp.svg b/assets/img/ar-mcp.svg new file mode 100644 index 0000000..1efac72 --- /dev/null +++ b/assets/img/ar-mcp.svg @@ -0,0 +1,4 @@ + + + \ No newline at end of file diff --git a/assets/img/ar-oss-architecture-dark.svg b/assets/img/ar-oss-architecture-dark.svg new file mode 100644 index 0000000..1cfbeee --- /dev/null +++ b/assets/img/ar-oss-architecture-dark.svg @@ -0,0 +1,4 @@ + + +UI · CLI · REST APIRegistry server(install once)PostgreSQLkagent (Kubernetes)agentregistry3rd-party componentsRuntimesCLIENTSCONTROL PLANERUNTIMESPersist registry state \ No newline at end of file diff --git a/assets/img/ar-oss-architecture.svg b/assets/img/ar-oss-architecture.svg index 3129b9b..8c5be26 100644 --- a/assets/img/ar-oss-architecture.svg +++ b/assets/img/ar-oss-architecture.svg @@ -1,4 +1,4 @@ -UI · CLI · REST APIRegistry server(install once)PostgreSQLkagent (Kubernetes)agentregistry3rd-party componentsRuntimesCLIENTSCONTROL PLANERUNTIMESPersist registry stateLocal (Docker) \ No newline at end of file +UI · CLI · REST APIRegistry server(install once)PostgreSQLkagent (Kubernetes)agentregistry3rd-party componentsRuntimesCLIENTSCONTROL PLANERUNTIMESPersist registry state \ No newline at end of file diff --git a/assets/img/ar-publish-skill-dark.svg b/assets/img/ar-publish-skill-dark.svg new file mode 100644 index 0000000..2831751 --- /dev/null +++ b/assets/img/ar-publish-skill-dark.svg @@ -0,0 +1,4 @@ + + + \ No newline at end of file diff --git a/assets/img/ar-publish-skill.svg b/assets/img/ar-publish-skill.svg new file mode 100644 index 0000000..24d9508 --- /dev/null +++ b/assets/img/ar-publish-skill.svg @@ -0,0 +1,4 @@ + + + \ No newline at end of file diff --git a/assets/img/kagent-servers-dark.svg b/assets/img/kagent-servers-dark.svg new file mode 100644 index 0000000..a5a014c --- /dev/null +++ b/assets/img/kagent-servers-dark.svg @@ -0,0 +1,4 @@ + + + \ No newline at end of file diff --git a/assets/img/kagent-servers.svg b/assets/img/kagent-servers.svg new file mode 100644 index 0000000..7872077 --- /dev/null +++ b/assets/img/kagent-servers.svg @@ -0,0 +1,4 @@ + + + \ No newline at end of file diff --git a/assets/img/mcp-connect-dark.svg b/assets/img/mcp-connect-dark.svg new file mode 100644 index 0000000..216d0a0 --- /dev/null +++ b/assets/img/mcp-connect-dark.svg @@ -0,0 +1,4 @@ + + + \ No newline at end of file diff --git a/assets/img/mcp-connect.svg b/assets/img/mcp-connect.svg new file mode 100644 index 0000000..9cbdd02 --- /dev/null +++ b/assets/img/mcp-connect.svg @@ -0,0 +1,4 @@ + + + \ No newline at end of file diff --git a/assets/img/mcp-greeting-dark.svg b/assets/img/mcp-greeting-dark.svg new file mode 100644 index 0000000..8a4e3e2 --- /dev/null +++ b/assets/img/mcp-greeting-dark.svg @@ -0,0 +1,4 @@ + + + \ No newline at end of file diff --git a/assets/img/mcp-greeting.svg b/assets/img/mcp-greeting.svg new file mode 100644 index 0000000..2e1d84e --- /dev/null +++ b/assets/img/mcp-greeting.svg @@ -0,0 +1,4 @@ + + + \ No newline at end of file diff --git a/content/docs/about/about.md b/content/docs/about/about.md index b1490f1..34fb6f0 100644 --- a/content/docs/about/about.md +++ b/content/docs/about/about.md @@ -52,7 +52,7 @@ Learn how agentregistry allows you to overcome the challenge of managing AI arti Agentregistry provides built-in tooling to help developers manage the entire lifecycle of AI artifacts, including agents, MCP servers, skills, prompts, and plugins. -With the `arctl` CLI, you can scaffold new artifacts from templates, build and package them as Docker images, run them locally to verify they work, and publish them to agentregistry with a single command. Once published, artifacts can be pulled from the registry and deployed to a developer's local machine or a Kubernetes cluster, without any complex deployment configuration. +With the `arctl` CLI, you can scaffold new artifacts from templates, build and package them as Docker images, run them locally to verify they work, and publish them to agentregistry with a single command. Once published, artifacts can be pulled from the registry and deployed to a Kubernetes cluster, without any complex deployment configuration. Before deploying agents to agentic platforms, developers can use agentregistry to compose agents by selecting specific MCP servers, skills, and prompts to attach. This composition approach lets developers assemble powerful, customized agents from proven, tested registry components rather than building everything from scratch. diff --git a/content/docs/about/architecture.md b/content/docs/about/architecture.md index d9e56c9..6a39f15 100644 --- a/content/docs/about/architecture.md +++ b/content/docs/about/architecture.md @@ -10,7 +10,7 @@ Agentregistry is a single control plane that you install once and connect to one The following diagram shows the components that make up agentregistry and how they relate to each other. -{{< reuse-image src="img/ar-oss-architecture.svg" >}} +{{< reuse-image src="img/ar-oss-architecture.svg" srcDark="img/ar-oss-architecture-dark.svg" >}} ### Registry server @@ -36,10 +36,6 @@ You interact with the registry through three interfaces, all served by the regis A **runtime** is a platform that the control plane connects to in order to deploy agents and MCP servers, or discover existing agents. One registry can connect to multiple runtimes at the same time. -### Docker (local) - -When you install agentregistry with Docker Compose, the Docker daemon on your local machine acts as the deployment target. The registry server runs alongside the bundled PostgreSQL container in the Compose stack. Agents and MCP servers are run as containers on the same Docker host. - ### Kubernetes When you install agentregistry in a Kubernetes cluster, the registry connects to [kagent](https://kagent.dev) to deploy and manage agents and MCP servers as Kubernetes workloads. The registry server runs as a Deployment in the `agentregistry` namespace and communicates with the kagent controller to materialize catalog entries as native Kubernetes resources. @@ -48,7 +44,6 @@ When you install agentregistry in a Kubernetes cluster, the registry connects to ## Next steps {{< cards >}} -{{< card link="/docs/concepts/" title="Core concepts" description="Understand the catalog, artifact types, runtimes, and management interfaces." >}} -{{< card link="/docs/setup/docker/" title="Install with Docker" description="Install agentregistry for local development with Docker." >}} +{{< card link="/docs/about/concepts/" title="Core concepts" description="Understand the catalog, artifact types, runtimes, and management interfaces." >}} {{< card link="/docs/setup/kubernetes/" title="Install on Kubernetes" description="Install agentregistry in a Kubernetes cluster with Helm." >}} {{< /cards >}} diff --git a/content/docs/about/concepts.md b/content/docs/about/concepts.md index c47f3eb..bb9be83 100644 --- a/content/docs/about/concepts.md +++ b/content/docs/about/concepts.md @@ -33,7 +33,7 @@ An **agent** is a deployable unit that you publish, version, and deploy to a run ### MCP servers -An **MCP server** exposes tools that agents can call at runtime. Agentregistry supports the full development lifecycle for MCP servers: scaffold a server, build and package it as a Docker image, publish it to the catalog, and deploy it to a local environment or a Kubernetes cluster. +An **MCP server** exposes tools that agents can call at runtime. Agentregistry supports the full development lifecycle for MCP servers: scaffold a server, build and package it as a Docker image, publish it to the catalog, and deploy it to a Kubernetes cluster. ### Skills @@ -54,11 +54,10 @@ A **plugin** is a versioned bundle of agent capabilities, including skills, MCP ## Runtimes -A **runtime** is a platform where agentregistry deploys and manages agents and MCP servers. +A **runtime** is a platform where agentregistry deploys and manages agents and MCP servers. The following runtime types are supported. | Runtime | Description | |---|---| -| **Docker** | Run agents and MCP servers on your local machine or a VM by using Docker Compose. This is the default runtime for local development. | | **Kubernetes** | Deploy agents and MCP servers to a Kubernetes cluster by using the [kagent open source project](https://kagent.dev). This is the recommended runtime for shared team environments. | ## Management interfaces diff --git a/content/docs/agents/create.md b/content/docs/agents/create.md index 484fc95..45f794f 100644 --- a/content/docs/agents/create.md +++ b/content/docs/agents/create.md @@ -1,75 +1,82 @@ --- title: Create and run weight: 10 -description: "Create an agent and run it locally using agentregistry's built-in agent templates." +description: "Scaffold an agent and run it locally by using agentregistry." --- -Quickly create an agent and run it on your local machine with built-in agent templates. - ## Before you begin -1. Follow the [Get started](/docs/quickstart/) guide to set up agentregistry and start the agentregistry daemon. -2. Install [`uv`](https://docs.astral.sh/uv/getting-started/installation/). +1. Follow the [Get started](/docs/quickstart/) guide to set up agentregistry and start the agentregistry daemon. +2. Install [`uv`](https://docs.astral.sh/uv/getting-started/installation/). ## Create an agent -Agentregistry comes with built-in agent templates that you can use to quickly spin up agents or customize them to your needs. +1. Create an agent. -1. Create an agent. + The following command creates a `myagent` Python agent with the Google ADK agent framework that is configured to use the Gemini provider. When you run the command, a `myagent` directory is created on your local machine that contains the scaffold for your agent. You see the directory structure in your CLI output. The agent has built-in skills to roll a die and check whether a number is prime. - The following command creates a `myagent` Python agent with the Google ADK agent framework that is configured to use the Gemini provider. When you run the command, a `myagent` directory is created on your local machine that contains the scaffold for your agent. ```sh - arctl agent init adk python myagent + arctl init agent myagent --framework adk --language python --model-provider gemini --model-name gemini-2.5-flash ``` -2. Explore the agent scaffold that was created for you. You can optionally make changes to the files to customize your agent further. + Example output: + ```console + ✓ Created agent: myagent (framework: adk, language: python, model: gemini/gemini-2.5-flash) + + 🚀 Next steps: + 1. Run locally (optional): + arctl run myagent + (export GOOGLE_API_KEY in your shell or set it in .env first) + 2. Publish to the registry: + arctl apply -f myagent/agent.yaml ``` + +2. Explore the agent scaffold. You can make changes to the files to customize your agent. + + ```sh ls myagent ``` - Example output: - ``` - agent.yaml docker-compose.yaml Dockerfile myagent pyproject.toml README.md + Example output: + ```console + agent.yaml arctl.yaml Dockerfile docker-compose.yaml .env myagent/ pyproject.toml README.md ``` - > [!NOTE] - > The `agent.yaml` file sets the image location that is used by agentregistry when you build the image and push it to your container registry. By default, agentregistry uses `ghcr.io` as the container registry and `latest` as the image tag, such as `ghcr.io/myagent:latest`. If you want to use agentregistry to push images to your container registry, make sure to update this file with the registry and image tag that you want to use. Note that this update is not required if you want to build images locally only without pushing them to your container registry. - - | File | Description | - | -- | -- | - | `agent.yaml` | The agent definition. This definition holds the registry location and version tag that you want to use when building and pushing the image to your registry. It also adds the MCP server references that you added to the agent. | - | `docker-compose.yaml` | A Docker compose file that is used to spin up and run your agent when you use the `arctl agent run` command. | - | `Dockerfile` | The Dockerfile to spin up and run your agent in a containerized environment. | - | `myagent` | A directory that includes the `agent.py` script that defines the agent, including the provider and model that you want to use. The directory also includes the agent card for agent discovery. | - | `pyproject.toml` | The dependency definition of your agent. | - | `README.md` | An introduction to the agent that you created with instructions for how to further customize it. | - + | File | Description | + | --- | --- | + | `agent.yaml` | The v1alpha1 agent definition. Contains the image reference, MCP server attachments, and other catalog metadata. Apply this file to publish the agent to the registry. | + | `arctl.yaml` | Local build config that records the framework, language, and environment variable requirements for this project. Used by `arctl run` and `arctl build`. | + | `.env` | Environment variables the framework needs at runtime, such as API keys. This file is gitignored. | + | `Dockerfile` | Builds the agent container image. | + | `docker-compose.yaml` | Used by `arctl run` to start the agent locally. | + | `myagent/` | Contains the agent source code, including the agent definition and the agent card. | + | `pyproject.toml` | Python project dependencies. | + | `README.md` | Introduction and customization instructions for the scaffolded agent. | ## Run the agent -1. Save your Gemini API key as an environment variable. To retrieve your API key, log in to the [Google AI Studio and select API Keys](https://aistudio.google.com/app/api-keys). This key is required to interact with the agent through the Gemini LLM provider. +1. Set your Gemini API key. You can retrieve it from the [Google AI Studio](https://aistudio.google.com/app/api-keys). + ```sh export GOOGLE_API_KEY= ``` -2. Run the agent on your local machine. +2. Run the agent locally. - The following command builds the agent image on your local machine by using the image location and tag that is defined in the `agent.yaml` file. Then, it opens a terminal window where you can start chatting with your agent. ```sh - arctl agent run myagent + arctl run myagent ``` - {{< reuse-image src="img/ar-run-agent.png" >}} - {{< reuse-image-dark srcDark="img/ar-run-agent.png" >}} - -3. Chat with the agent. For example, you can ask it what it can do for you. Then, hit **Enter** and wait for the agent to reply. - - {{< reuse-image src="img/ar-run-agent-chat.png" >}} - {{< reuse-image-dark srcDark="img/ar-run-agent-chat.png" >}} + {{< reuse-image src="img/ar-run-agent.png" srcDark="img/ar-run-agent.png" >}} + +3. Chat with the agent. For example, you can ask it what it can do for you. + + {{< reuse-image src="img/ar-run-agent-chat.png" srcDark="img/ar-run-agent-chat.png" >}} -4. Exit the agent by using the `ctrl + c` keys. +4. Exit the agent with **Ctrl+C**. ## Next -[Publish your agent](/docs/agents/publish/) to agentregistry so that you can start deploying it to your environments. - \ No newline at end of file +{{< cards >}} +{{< card link="../publish/" title="Publish the agent" description="Build and publish your agent to the agentregistry catalog." >}} +{{< /cards >}} diff --git a/content/docs/agents/deploy/kubernetes.md b/content/docs/agents/deploy/kubernetes.md index cf5b477..dd4c22e 100644 --- a/content/docs/agents/deploy/kubernetes.md +++ b/content/docs/agents/deploy/kubernetes.md @@ -8,23 +8,9 @@ Deploy your agent to a Kubernetes cluster. ## Before you begin -1. Follow the [Get started](/docs/quickstart/) guide to set up agentregistry and start the agentregistry daemon. -2. [Publish an agent](/docs/agents/publish/). -3. Create a Kubernetes cluster. For example, you can use the following command to create a `kind` cluster. - ```sh - kind create cluster --name agentregistry - ``` -4. Make sure that your current kubeconfig context points to the cluster that you want to use. - ```sh - kubectl config get-contexts - ``` -5. Follow the [Quickstart](https://kagent.dev/docs/kagent/getting-started/quickstart) in the kagent OSS documentation. Agentregistry uses kagent for bootstrapping during an agent deployment. - -6. **Local setups only**: If you built the docker images locally without pushing them to a registry, load the agent and MCP server images to your kind or minikube cluster. The following command assumes that you use kind and that your cluster is named agentregistry. - ```sh - kind load docker-image ghcr.io/myagent:latest --name agentregistry - kind load docker-image my-mcp-server:latest --name agentregistry - ``` +1. Follow the [Get started](/docs/quickstart/) guide to install agentregistry. +2. [Connect a runtime]({{< link path="/setup/runtime/" >}}) to install kagent and verify that the `kubernetes-default` runtime is registered. +3. [Publish an agent](/docs/agents/publish/). ## Deploy the agent {#deploy} diff --git a/content/docs/agents/deploy/local.md b/content/docs/agents/deploy/local.md deleted file mode 100644 index ac1f8e7..0000000 --- a/content/docs/agents/deploy/local.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: Local -weight: 10 -description: Deploy an agent from agentregistry to your local environment. ---- - -Deploy an agent from agentregistry to your local environment. - -> [!NOTE] -> To deploy an agent to a local environment, you must install agentregistry by using Docker as shown in the [Get started](/docs/quickstart/) guide. If you installed agentregistry on Kubernetes, you cannot deploy to local environments. - -Local deployments spin up Docker containers on your local machine from images that exist on your machine or that can be pulled from the image location reference that agentregistry points to. - -## Before you begin - -1. Follow the [Get started](/docs/quickstart/) guide to set up agentregistry and start the agentregistry daemon. -2. [Publish an agent](/docs/agents/publish/). - -## Deploy the agent - -1. Save your Gemini API key as an environment variable. To retrieve your API key, log in to the [Google AI Studio and select API Keys](https://aistudio.google.com/app/api-keys). The key is used to interact with the agent via the Gemini LLM provider. - ```sh - export GOOGLE_API_KEY= - ``` - -2. Deploy the agent to your local environment. The following command spins up a Docker container by using Docker compose. - ```sh - arctl deployments create myagent --type agent - ``` - - Example output: - ```console - Agent 'myagent' version 'latest' deployed to local provider (providerId=local) - ``` - - > [!NOTE] - > If the deployment fails, a deployment entry is still created in the database and set to failed. You can view failed deployments by using the `arctl deployments list` command. Note that you cannot re-deploy a failed deployment to fix it. Instead, remove the failed deployment with `arctl deployments delete ` and then re-run the `arctl deployments create` command. - -3. Verify that the deployment was created. - ```sh - arctl deployments list - ``` - - Example output: - ```console - ID NAME VERSION TYPE PROVIDER STATUS AGE - be6b09e5 myagent latest agent local deployed 1m - ``` - -4. Optional: [Open the agentregistry UI](http://localhost:12121) and go to the **Deployed** view. Verify that you see the deployed agent. - - {{< reuse-image src="img/ar-agent-deploy-verify.png" >}} - {{< reuse-image-dark srcDark="img/ar-agent-deploy-verify-dark.png" >}} - - - -## Cleanup - -You can remove a deployment from the UI or CLI. - -{{< tabs >}} -{{% tab name="UI" %}} - -1. [Open the agentregistry UI](http://localhost:12121) and go to the **Deployed** view. -2. Find the agent deployment that you want to remove and click the trash icon. - -{{% /tab %}} -{{% tab name="CLI" %}} - -1. List the deployments in your environment and find the one that you want to delete. - ```sh - arctl deployments list - ``` - -2. Remove the deployment. - ```sh - arctl deployments delete - ``` - -{{% /tab %}} -{{< /tabs >}} - diff --git a/content/docs/agents/mcp.md b/content/docs/agents/mcp.md index 9c3d6f2..d4e3b8b 100644 --- a/content/docs/agents/mcp.md +++ b/content/docs/agents/mcp.md @@ -10,8 +10,8 @@ Give an agent access to the tools that are exposed on an MCP server. 1. Follow the [Get started](/docs/quickstart/) guide to set up agentregistry and start the agentregistry daemon. 2. [Create an agent](/docs/agents/create/). -3. [Create an MCP server](/docs/mcp/create/). -4. [Publish an MCP server](/docs/mcp/publish/). +3. [Create an MCP server](/docs/mcp/local/create/). +4. [Publish an MCP server](/docs/mcp/local/publish/). ## Add MCP server diff --git a/content/docs/agents/publish.md b/content/docs/agents/publish.md index 95e2998..d451901 100644 --- a/content/docs/agents/publish.md +++ b/content/docs/agents/publish.md @@ -4,91 +4,66 @@ weight: 20 description: "Add your agent to the registry catalog." --- -Build and publish your agent image in agentregistry by using the `arctl agent build` and `arctl agent publish` commands. - -## About publishing agents - -Agentregistry serves as a catalog for your AI artifacts, including agents, skills, and MCP servers. To control which images you want to make available to your teams, you can use the publishing capability in agentregistry. If an image is published, a reference to its container image location is stored in agentregistry. This allows teams to quickly discover approved agents and deploy them to their environments. - -Before you can publish an image reference, you must first build the image. Agentregistry provides the following options for building your agent images: - -* **Build the image locally**. This option assumes that you want to build the agent image on your local machine only, such as for local test setups. The image is not pushed to your container registry. While you can still create a catalog entry for the agent image in agentregistry by using the `arctl agent publish` command, you cannot deploy the image to a Kubernetes cluster, unless you manually load the image to your cluster. -* **Build and push**: This process allows you to build the agent image on your local machine and push it to your container registry. Note that this option requires you to be logged into the container registry that you want to use and that the `agent.yaml` file includes the correct container registry and image tag details. - -For testing purposes, the instructions in this guide assume that you do not want to use agentregistry to push the image to your container registry. +Build your agent image and publish it to agentregistry so your team can discover and deploy it. ## Before you begin -1. Follow the [Get started](/docs/quickstart/) guide to set up agentregistry and start the agentregistry daemon. -2. [Create an agent](/docs/agents/create/). +1. Follow the [Get started](/docs/quickstart/) guide to set up agentregistry and start the agentregistry daemon. +2. [Create an agent](/docs/agents/create/). -## Publish the agent image +## Publish the agent -1. Build the agent image on your local machine. The following command builds the image with the Dockerfile that is included in your `myagent` scaffold and tags it with the container registry and version information that is provided in the `agent.yaml` file. If you followed the instructions in this guide, `ghcr.io/myagent:latest` is used. +1. Build the agent Docker image. The following command reads `arctl.yaml` in your project directory and builds the image tag from your `agent.yaml`. To push the image to a container registry, add `--push`. Make sure you are logged in to the registry before adding `--push`. ```sh - arctl agent build myagent + arctl build myagent ``` - Example output: + Example output: ```console - [+] Building 48.4s (12/12) FINISHED docker:desktop-linux - => [internal] load build definition from Dockerfile 0.1s - => => transferring dockerfile: 384B 0.0s - => [internal] load metadata for ghcr.io/kagent-dev/kagent/kagent-adk:0.7.4 + [+] Building 48.4s (12/12) FINISHED ... ✅ Successfully built Docker image: ghcr.io/myagent:latest ``` > [!TIP] - > To also use agentregistry to push the image to your container registry, include the `--push` option. You can also set the platform, for which you want to build the image, such as `linux/amd64` by using the `--platform` option. For more information, see the [arctl agent build](/docs/reference/cli/arctl-agent-build/) command. Make sure that you are logged in to your container registry before you run the command. + > To build for a specific platform, add `--platform linux/amd64`. To override the image tag, use `--image ghcr.io/myorg/myagent:v1.0.0`. For more information, see the [arctl build](/docs/reference/cli/arctl-build/) command. + +2. Publish the agent to agentregistry. The following command registers your `agent.yaml` definition in the catalog. -2. Verify that the image is built. ```sh - docker images | grep ghcr.io/myagent + arctl apply -f myagent/agent.yaml ``` - Example output: + Example output: ```console - ghcr.io/myagent latest b530ddc3c8d8 11 minutes ago 2.9GB + agent.agentregistry.dev/myagent applied ``` -3. Publish the agent in agentregistry. The following command adds a reference to your image location in agentregistry. - ```sh - arctl agent publish myagent - ``` - - Example output: - ``` - Agent 'myagent' version latest published successfully - ``` +3. List the agents in agentregistry. Verify that you see an entry for `myagent`. -4. List the agent image references in agentregistry. Verify that you see an entry for the `myagent` agent image that you just published. ```sh - arctl agent list + arctl get agents ``` Example output: - ``` - NAME VERSION FRAMEWORK LANGUAGE PROVIDER MODEL DEPLOYED PUBLISHED - myagent latest adk python gemini gemini-2.0-flash False True + ```console + NAME FRAMEWORK LANGUAGE PROVIDER MODEL DEPLOYED PUBLISHED + myagent adk python gemini gemini-2.0-flash False True ``` -5. Optional: Open the [agentregistry UI](http://localhost:12121) and go to the **Agents** view. Verify that you can see your agent image reference. +4. Optional: Open the [agentregistry UI](http://localhost:12121) and go to the **Agents** view. Verify that you can see your agent. {{< reuse-image src="img/ar-list-agent.png" >}} {{< reuse-image-dark srcDark="img/ar-list-agent-dark.png" >}} - You can also select the agent to view the agent details, such as the agent YAML definition and image tag. - ## Next -Now that you published the agent image, you can [deploy the agent to your environment](/docs/agents/deploy/). - +Now that you published the agent, you can [deploy the agent to your environment](/docs/agents/deploy/). ## Cleanup -To remove an agent image from agentregistry, use the `arctl agent delete` command. +To remove an agent from agentregistry, use `arctl delete`. ```sh -arctl agent delete myagent --version latest -``` \ No newline at end of file +arctl delete agent myagent +``` diff --git a/content/docs/agents/skills.md b/content/docs/agents/skills.md index 43c62a5..2f39dca 100644 --- a/content/docs/agents/skills.md +++ b/content/docs/agents/skills.md @@ -10,7 +10,7 @@ Give an agent access to skills that are published in agentregistry. Skills are l 1. Follow the [Get started](/docs/quickstart/) guide to set up agentregistry and start the agentregistry daemon. 2. [Create an agent](/docs/agents/create/). -3. [Create a skill](/docs/skills/create/) and [publish it](/docs/skills/publish/) to agentregistry. +3. [Create and publish a skill](/docs/skills/publish/) to agentregistry. ## Add a skill diff --git a/content/docs/mcp/create.md b/content/docs/mcp/create.md deleted file mode 100644 index 644855e..0000000 --- a/content/docs/mcp/create.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: Create and run -weight: 10 -description: "Build and run MCP servers on your local machine with agentregistry." ---- - -Quickly build and run MCP servers on your local machine. - -## Before you begin - -1. Follow the [Get started](/docs/quickstart/) guide to set up agentregistry and start the agentregistry daemon. -2. Install [`uv`](https://docs.astral.sh/uv/getting-started/installation/). - -## Create an MCP server - -Agentregistry comes with built-in MCP server templates that you can use to quickly spin up MCP servers or customize them to your needs. - -1. Create an MCP server. Enter an optional description, author name, and email, or skip these by pressing the return key. - - The following command creates a `my-mcp-server` FastMCP server with an echo tool. When you run the command, a `my-mcp-server` directory is created on your local machine that contains the scaffold for your MCP server. - ```sh - arctl mcp init python my-mcp-server - ``` - -2. Explore the MCP server scaffold that was created for you. You can optionally make changes to the files to customize your agent further. - ``` - ls -R my-mcp-server - ``` - - Example output: - ``` - Dockerfile mcp.yaml pyproject.toml README.md src tests - - my-mcp-server/src: - core main.py tools - - my-mcp-server/src/core: - __init__.py server.py utils.py - - my-mcp-server/src/tools: - __init__.py echo.py - - my-mcp-server/tests: - test_discovery.py test_server.py test_tools.py - ``` - - | File | Description | - | -- | -- | - | `Dockerfile` | The Dockerfile to spin up and run your MCP server in a containerized environment. | - | `mcp.yaml` | The MCP server configuration file that defines server metadata, transport settings, version, and other server-specific configuration. | - | `pyproject.toml` | The Python project configuration file that defines project dependencies, build settings, and metadata for the MCP server. | - | `README.md` | An introduction to the MCP server that you created with instructions for how to further customize it. | - | `src` | A directory that contains the details of the MCP server, such as supported tools and the Python script to bootstrap and run the server. | - | `tests` | A directory that contains generated tests. | - - -## Run the MCP server - -1. Start the MCP server. In your CLI output, note the MCP server URL. In the following example, the MCP server address is `http://localhost:57196/mcp`. - ```sh - arctl mcp run my-mcp-server - ``` - - Example output: - ```console - Running local MCP server: my-mcp-server (version 0.1.0) - Using Docker image: my-mcp-server:0.1.0 - - MCP Server URL: http://localhost:57196/mcp - - Press CTRL+C to stop the server... - - 2026-01-27 22:12:40,261 - INFO - Loaded tool module: echo - 2026-01-27 22:12:40,261 - INFO - 📦 Successfully loaded 1 tools - 2026-01-27 22:12:40,647 - INFO - HTTP Request: GET https://pypi.org/pypi/fastmcp/json "HTTP/1.1 200 OK" - ... - ``` - -2. Open the MCP inspector tool. - ```sh - npx modelcontextprotocol/inspector#0.18.0 - ``` - -3. Connect to your MCP server. Enter the following details. - * Transport type: Select **Streamable HTTP**. - * URL: The MCP server URL that you retrieved earlier, such as `http://localhost:57196/mcp`. - * Click **Connect**. - -4. Go to the **Tools** tab and select the `echo` tool. Enter any string in the `message` field, and click **Run Tool**. Verify that your string is echoed back to you. - {{< reuse-image src="img/mcp-tool-call.png" >}} - {{< reuse-image-dark srcDark="img/mcp-tool-call-dark.png" >}} - - -## Next - -Explore the following tasks: - -* [Add a tool](/docs/mcp/tools) to your MCP server. -* [Publish the MCP server to agentregistry](/docs/mcp/publish). - diff --git a/content/docs/mcp/deploy/_index.md b/content/docs/mcp/deploy/_index.md deleted file mode 100644 index 9393d79..0000000 --- a/content/docs/mcp/deploy/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Deploy -weight: 30 -description: "Deploy MCP servers built with agentregistry to your target environment." ---- \ No newline at end of file diff --git a/content/docs/mcp/deploy/kubernetes.md b/content/docs/mcp/deploy/kubernetes.md deleted file mode 100644 index 142f3a8..0000000 --- a/content/docs/mcp/deploy/kubernetes.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: Kubernetes -weight: 20 -description: "Deploy your agentregistry MCP server to a Kubernetes cluster." ---- - -Deploy your agent to a Kubernetes cluster. - -## Before you begin - -1. Follow the [Get started](/docs/quickstart/) guide to set up agentregistry and start the agentregistry daemon. -2. [Publish an MCP server](/docs/mcp/publish/). -3. Create a Kubernetes cluster. For example, you can use the following command to create a `kind` cluster. - ```sh - kind create cluster --name agentregistry - ``` -4. Make sure that your current kubeconfig context points to the cluster that you want to use. - ```sh - kubectl config get-contexts - ``` -5. Follow the [Quickstart](https://kagent.dev/docs/kagent/getting-started/quickstart) in the kagent OSS documentation. Agentregistry uses kagent for bootstrapping during an MCP server deployment. - -6. **Local setups only**: If you built the docker images locally without pushing them to a registry, load the MCP server image to your kind or minikube cluster. The following command assumes that you use kind and that your cluster is named agentregistry. - ```sh - kind load docker-image my-mcp-server:latest --name agentregistry - ``` - - -## Deploy the MCP server {#deploy} - -1. Deploy the MCP server to your cluster. - ```sh - arctl deployments create user/my-mcp-server \ - --type mcp \ - --provider-id kubernetes-default \ - --namespace default \ - --version 0.1.0 - ``` - - Example output: - ```console - Deploying server... - - Deployed user/my-mcp-server (v0.1.0) with providerId=local - - Server deployment recorded. The registry will reconcile containers automatically. - Agent Gateway endpoint: http://localhost:21212/mcp - ``` - - > [!NOTE] - > If the deployment fails, a deployment entry is still created in the database and set to failed. You can view failed deployments by using the `arctl deployments list` command. Note that you cannot re-deploy a failed deployment to fix it. Instead, remove the failed deployment with `arctl deployments delete ` and then re-run the `arctl deployments create` command. - -2. Verify that the MCP server is up and running. - ```sh - kubectl get pods | grep mcp - ``` - - Example output: - ```console - NAME READY STATUS RESTARTS AGE - user-my-mcp-server-1a1a3db9-9b5fbbd94-5c6k9 1/1 Running 61s - ``` - -3. Optional: Review the MCPServer resource that was created in your cluster. - ```sh - kubectl get mcpserver -o yaml - ``` - - - -## Cleanup - -You can remove a deployment from the UI or CLI. - -{{< tabs >}} -{{% tab name="UI" %}} - -1. [Open the agentregistry UI](http://localhost:12121) and go to the **Deployed** view. -2. Find the MCP server deployment that you want to remove and click the trash icon. - -{{% /tab %}} -{{% tab name="CLI" %}} - -1. List the deployments in your environment and find the one that you want to delete. - ```sh - arctl deployments list - ``` - -2. Remove the deployment. - ```sh - arctl deployments delete - ``` - -{{% /tab %}} -{{< /tabs >}} diff --git a/content/docs/mcp/deploy/local.md b/content/docs/mcp/deploy/local.md deleted file mode 100644 index 2cb3fe4..0000000 --- a/content/docs/mcp/deploy/local.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -title: Local -weight: 10 -description: Deploy an agent from agentregistry to your local environment. ---- - -Deploy an MCP server from agentregistry to your local environment. - -> [!NOTE] -> To deploy an MCP server to a local environment, you must install agentregistry by using Docker as shown in the [Get started](/docs/quickstart/) guide. If you installed agentregistry on Kubernetes, you cannot deploy to local environments. - -Local deployments spin up Docker containers on your local machine from images that exist on your machine or that can be pulled from the image location reference that agentregistry points to. - -## Before you begin - -1. Follow the [Get started](/docs/quickstart/) guide to set up agentregistry and start the agentregistry daemon. -2. [Publish an MCP server](/docs/mcp/publish/). - -## Deploy the MCP server - - -1. List the MCP servers that are published to agentregistry. - ```sh - arctl mcp list - ``` - - Example output: - ``` - NAME VERSION TYPE DEPLOYED UPDATED - user/my-mcp-server 0.1.0 oci False 2h - ``` - -2. Deploy the MCP server to your local environment. The following command spins up a Docker container from the `user/my-mcp-server` artifact reference that is published in agentregistry. In your CLI output, get the address that the MCP server is exposed on. - ```sh - arctl deployments create user/my-mcp-server \ - --type mcp \ - --version 0.1.0 - ``` - - Example output: - ```console - Deployed user/my-mcp-server (v0.1.0) with providerId=local - - Server deployment recorded. The registry will reconcile containers automatically. - Agent Gateway endpoint: http://localhost:21212/mcp - ``` - - > [!NOTE] - > If the deployment fails, a deployment entry is still created in the database and set to failed. You can view failed deployments by using the `arctl deployments list` command. Note that you cannot re-deploy a failed deployment to fix it. Instead, remove the failed deployment with `arctl deployments delete ` and then re-run the `arctl deployments create` command. - -3. Open the MCP inspector. - ```sh - npx modelcontextprotocol/inspector#0.18.0 - ``` - -4. Connect to your MCP server. Enter the following details. - * Transport type: Select **Streamable HTTP**. - * URL: The MCP server URL that you retrieved earlier, such as `http://localhost:21212/mcp`. - * Click **Connect**. - -5. Go to the **Tools** tab and verify that you see the newly added `add_number` tool. Try out the tool by entering two integer numbers, such as 5 and 3. Then, click **Run Tool**. Verify that the sum of both numbers is returned. - {{< reuse-image src="img/mcp-add-tool.png" >}} - {{< reuse-image-dark srcDark="img/mcp-add-tool-dark.png" >}} - - - -## Cleanup - -You can remove a deployment from the UI or CLI. - -{{< tabs >}} -{{% tab name="UI" %}} - -1. [Open the agentregistry UI](http://localhost:12121) and go to the **Deployed** view. -2. Find the MCP server deployment that you want to remove and click the trash icon. - -{{% /tab %}} -{{% tab name="CLI" %}} - -1. List the deployments in your environment and find the one that you want to delete. - ```sh - arctl deployments list - ``` - -2. Remove the deployment. - ```sh - arctl deployments delete - ``` - -{{% /tab %}} -{{< /tabs >}} - - diff --git a/content/docs/mcp/local/_index.md b/content/docs/mcp/local/_index.md new file mode 100644 index 0000000..f2673b6 --- /dev/null +++ b/content/docs/mcp/local/_index.md @@ -0,0 +1,5 @@ +--- +title: Local development +weight: 10 +description: "Create, build, publish, and deploy MCP servers with agentregistry." +--- diff --git a/content/docs/mcp/local/create.md b/content/docs/mcp/local/create.md new file mode 100644 index 0000000..2509edb --- /dev/null +++ b/content/docs/mcp/local/create.md @@ -0,0 +1,91 @@ +--- +title: Create and run +weight: 10 +description: "Build and run MCP servers on your local machine with agentregistry." +--- + +## Before you begin + +1. Install agentregistry on [Kubernetes]({{< link path="/setup/kubernetes" >}}). +2. Install [`uv`](https://docs.astral.sh/uv/getting-started/installation/). + +## Create an MCP server + +Agentregistry comes with built-in MCP server templates that you can use to quickly spin up MCP servers or customize them to your needs. + +1. Scaffold an MCP server. The following command creates a `mymcp` directory with the FastMCP framework and Python. + + ```sh + arctl init mcp mymcp --framework fastmcp --language python + ``` + + Example output: + ```console + ✓ Created MCP server: mymcp (framework: fastmcp, language: python, transport: http, port: 3000) + + 🚀 Next steps: + 1. Run locally (optional): + arctl run my-mcp + 2. Publish to the registry: + arctl apply -f my-mcp/mcp.yaml + ``` + +2. Explore the MCP server scaffold. You can make changes to the files to customize your server. + + ```sh + ls mymcp + ``` + + Example output: + ```console + mcp.yaml arctl.yaml Dockerfile docker-compose.yaml .env pyproject.toml README.md src tests + ``` + + | File | Description | + | --- | --- | + | `mcp.yaml` | The v1alpha1 MCP server definition. Contains the image reference, transport settings, and catalog metadata. Apply this file to publish the server to the registry. | + | `arctl.yaml` | Local build config that records the framework, language, and transport settings. Used by `arctl run` and `arctl build`. | + | `.env` | Environment variables the server needs at runtime. This file is gitignored. | + | `Dockerfile` | Builds the MCP server container image. | + | `docker-compose.yaml` | Used by `arctl run` to start the server locally. | + | `pyproject.toml` | Python project dependencies. | + | `README.md` | Introduction and customization instructions for the scaffolded server. | + | `src/` | MCP server source code, including tool definitions and the server bootstrap script. The scaffold includes two example tools: `echo` and `sum`. | + | `tests/` | Generated tests for the server and its tools. | + +## Run the MCP server + +1. Run the MCP server on your local machine with the MCP Inspector. The `--inspector` flag starts the server and automatically opens the MCP Inspector so you can test your tools without any additional setup. + + ```sh + arctl run mymcp --inspector + ``` + + Example output: + ```console + → fastmcp-python: docker run --rm -p 3000:3000 localhost:5001/mymcp:latest --transport http --host 0.0.0.0 --port 3000 + 2026-05-14 18:39:46,327 - INFO - Loaded tool module: sum + 2026-05-14 18:39:46,329 - INFO - Loaded tool module: echo + 2026-05-14 18:39:46,329 - INFO - 📦 Successfully loaded 2 tools + ... + INFO Starting MCP server 'mymcp' with transport 'http' on http://0.0.0.0:3000/mcp + ``` + +2. Connect to your MCP server in the Inspector tool. + {{< reuse-image src="img/mcp-connect.svg" srcDark="img/mcp-connect-dark.svg" >}} + +3. Try out an MCP tool. + 1. Navigate to the **Tools** tab. Verify that you see the `example_echo` and `example_sum` tools. + 2. Select the `example_sum` tool and enter any two integer in the **a** and **b** fields. + 3. Click **Execute Tool** and verify that you see the sum of the two integers. + + {{< reuse-image src="img/ar-mcp-sum.svg" srcDark="img/ar-mcp-sum-dark.svg" >}} + +4. Exit the MCP Inspector and stop the server by pressing **Ctrl+C**. + +## Next + +{{< cards >}} +{{< card link="/docs/mcp/local/tools/" title="Add a tool" description="Add custom tools to your MCP server." >}} +{{< card link="/docs/mcp/local/publish/" title="Publish the MCP server" description="Build and publish your MCP server to the agentregistry catalog." >}} +{{< /cards >}} diff --git a/content/docs/mcp/local/deploy/_index.md b/content/docs/mcp/local/deploy/_index.md new file mode 100644 index 0000000..0510b40 --- /dev/null +++ b/content/docs/mcp/local/deploy/_index.md @@ -0,0 +1,5 @@ +--- +title: Deploy +weight: 30 +description: "Deploy MCP servers built with agentregistry to a Kubernetes cluster." +--- \ No newline at end of file diff --git a/content/docs/mcp/local/deploy/kagent.md b/content/docs/mcp/local/deploy/kagent.md new file mode 100644 index 0000000..ec09fc0 --- /dev/null +++ b/content/docs/mcp/local/deploy/kagent.md @@ -0,0 +1,157 @@ +--- +title: kagent +weight: 20 +description: "Deploy your agentregistry MCP server to a Kubernetes cluster." +--- + +## Before you begin + +1. Follow the [Get started]({{< link path="/quickstart/" >}}) guide to install agentregistry. +2. [Connect the kagent runtime]({{< link path="/setup/runtime/" >}}) so that you can deploy MCP servers to your Kubernetes cluster. +3. [Publish an MCP server]({{< link path="/mcp/local/publish/" >}}). +4. If you are using a kind cluster and pushed the image to a local registry rather than a remote one, load the image into the cluster. Replace `ghcr.io/my-org/mymcp:latest` with the image identifier from your `mcp.yaml` file and `` with the name of your kind cluster. + ```sh + kind load docker-image ghcr.io/my-org/mymcp:latest --name + ``` + +## Deploy the MCP server + +1. List the runtimes available in agentregistry. Verify that you see the `kubernetes-default` runtime, which is the runtime that you use to deploy MCP servers to Kubernetes by using the kagent OSS project. + + ```sh + arctl get runtimes + ``` + + Example output: + ```console + NAME TYPE + kubernetes-default Kubernetes + local Local + ``` + +2. Create a Deployment resource that deploys a published MCP server to the `kubernetes-default` runtime. + + ```yaml + arctl apply -f- < MCP & Tools** to see the `my-mcp` server and its tools listed. + + ```sh + kagent dashboard + ``` + + {{< reuse-image src="img/kagent-servers.svg" srcDark="img/kagent-servers-dark.svg" >}} + +## Cleanup + +1. List the deployments and find the one you want to delete. + ```sh + arctl get deployments + ``` + +2. Remove the deployment. + ```sh + arctl delete deployment my-mcp-server + ``` diff --git a/content/docs/mcp/local/publish.md b/content/docs/mcp/local/publish.md new file mode 100644 index 0000000..3e8e309 --- /dev/null +++ b/content/docs/mcp/local/publish.md @@ -0,0 +1,134 @@ +--- +title: Publish to catalog +weight: 20 +description: Add your MCP server to the agentregistry catalog so that you can start deploying the MCP server to connected runtimes. +--- + +## About the registry catalog + +Agentregistry serves as a catalog for your AI artifacts, including agents, skills, and MCP servers. You can decide which MCP servers you want to make available to your registry users by adding them to the registry catalog. After an MCP server is published in the catalog, registry users can deploy it to a connected runtime. + +Before you can add an MCP server to the catalog, you must build a Docker container image and push it to a container image registry. The registry deploys MCP servers from the container image. Optionally, you can also add a reference to the source code repository in your `mcp.yaml` file so that catalog users can trace the server back to its source. + +| Field | Purpose | Required for deployment? | +| --- | --- | --- | +| `spec.source.package` | The runnable container image. The registry deploys from this. | Yes | +| `spec.source.repository` | A link to the source code repository. Traceability metadata only — not used for deployment. | No | + +## Before you begin + +1. Install agentregistry on [Kubernetes]({{< link path="/setup/kubernetes" >}}). +2. [Create an MCP server]({{< link path="/mcp/local/create/" >}}). +3. Optional: [Add tools to your MCP server]({{< link path="/mcp/local/tools" >}}). + +## Build the image + +1. Set your container registry as an environment variable. The examples in this guide use GitHub Container Registry (`ghcr.io`). Replace `my-org` with your GitHub organization or username. + ```sh + export REGISTRY=ghcr.io/my-org + ``` + +2. Log in to your container registry. + ```sh + docker login ghcr.io + ``` + +3. Build the MCP server image from within the MCP project directory and push it to your registry. + + {{< tabs >}} + {{% tab name="Multi-arch (recommended)" %}} + Use the `docker buildx` command to build a multi-architecture image. + + ```sh + docker buildx build --platform linux/amd64,linux/arm64 \ + --label io.modelcontextprotocol.server.name="mymcp" \ + --tag $REGISTRY/mymcp:latest \ + --push . + ``` + + {{% /tab %}} + {{% tab name="Single-arch" %}} + Use the `arctl build` command for a single-architecture image. Pass the `--image` flag to set the full registry path and `--push` to push after building. + + ```sh + arctl build mymcp --image $REGISTRY/mymcp:latest --push + ``` + + Example output: + ```console + Building Docker image for python project... + ... + ✓ Successfully built Docker image: ghcr.io/my-org/mymcp:latest + ``` + + {{% /tab %}} + {{< /tabs >}} + +## Publish the server + +1. Write the `mcp.yaml` manifest. The `$REGISTRY` variable set in the build step is used here to keep the image path consistent. The registry validates that the image exists at apply time, so make sure the image is pushed before running this command. + + ```yaml + cat > mymcp/mcp.yaml << EOF + apiVersion: ar.dev/v1alpha1 + kind: MCPServer + metadata: + name: mymcp + spec: + title: mymcp + description: mymcp MCP server + source: + package: + origin: + type: oci + identifier: $REGISTRY/mymcp:latest + oci: + serverName: mymcp + transport: + type: http + port: 3000 + path: /mcp + EOF + ``` + +2. Publish the MCP server to the agentregistry catalog. + + ```sh + arctl apply -f mymcp/mcp.yaml + ``` + + Example output: + ```console + → Injecting labels from arctl.yaml: arctl.dev/framework=fastmcp, arctl.dev/language=python + ✓ MCPServer/mymcp (latest) created + ``` + +3. Verify that the MCP server is published in the catalog. + + ```sh + arctl get mcps + ``` + + Example output: + ```console + NAME TAG DESCRIPTION + mymcp latest mymcp MCP server + ``` + +4. Optional: Open the [agentregistry UI](http://localhost:12121) and go to the **Servers** view to review your published MCP server. + {{< reuse-image src="img/ar-mcp.svg" srcDark="img/ar-mcp-dark.svg" >}} + +## Next + +{{< cards >}} +{{< card link="/docs/mcp/local/deploy" title="Deploy the MCP server" description="Deploy your MCP server to a Kubernetes runtime." >}} +{{< card link="/docs/agents/mcp/" title="Add to an agent" description="Wire your MCP server into an agent." >}} +{{< /cards >}} + +## Cleanup + +To delete an MCP server from agentregistry, use `arctl delete`. + +```sh +arctl delete mcp mymcp +``` diff --git a/content/docs/mcp/local/tools.md b/content/docs/mcp/local/tools.md new file mode 100644 index 0000000..3838ce5 --- /dev/null +++ b/content/docs/mcp/local/tools.md @@ -0,0 +1,61 @@ +--- +title: Add tools +weight: 15 +description: "Add tools to your MCP server." +--- + +## Before you begin + +1. Install agentregistry on [Kubernetes]({{< link path="/setup/kubernetes" >}}). +2. [Create an MCP server]({{< link path="/mcp/local/create/" >}}). + +## Add a tool + +Each tool is a Python file in the `src/tools/` directory of your MCP scaffold. The file must import the shared `mcp` instance from `core.server` and define at least one function that is decorated with `@mcp.tool()`. The file is picked up automatically at server startup. + +1. Create a new tool file. The following command creates a greeting tool that takes a name as input and returns `Hello, {name}!`. + + ```sh + cat > mymcp/src/tools/greet.py << 'EOF' + from core.server import mcp + + @mcp.tool(description="Return a greeting for the given name.") + def example_greet(name: str) -> str: + return f"Hello, {name}!" + EOF + ``` + +2. Run the server with the MCP Inspector to verify the new tool is available. + + ```sh + arctl run mymcp --inspector + ``` + + Example output: + ```console + → fastmcp-python: docker run --rm -p 3000:3000 localhost:5001/mymcp:latest --transport http --host 0.0.0.0 --port 3000 + 2026-05-14 18:39:46,327 - INFO - Loaded tool module: sum + 2026-05-14 18:39:46,329 - INFO - Loaded tool module: echo + 2026-05-14 18:39:46,329 - INFO - Loaded tool module: greet + 2026-05-14 18:39:46,329 - INFO - 📦 Successfully loaded 3 tools + ... + INFO Starting MCP server 'mymcp' with transport 'http' on http://0.0.0.0:3000/mcp + ``` + +3. Connect to your MCP server in the Inspector tool. + {{< reuse-image src="img/mcp-connect.svg" srcDark="img/mcp-connect-dark.svg" >}} + +4. Try out the new tool. + 1. Navigate to the **Tools** tab. Verify that you see the `example_echo`, `example_sum`, and `example_greet` tools. + 2. Select the `example_greet` tool and enter any name in the **name** field, such as `me`. + 3. Click **Execute Tool** and verify that you see the `Hello, me!` message. + + {{< reuse-image src="img/mcp-greeting.svg" srcDark="img/mcp-greeting-dark.svg" >}} + +5. Exit the MCP Inspector and stop the server by pressing **Ctrl+C**. + +## Next + +{{< cards >}} +{{< card link="/docs/mcp/local/publish/" title="Publish the MCP server" description="Build and publish your MCP server to the agentregistry catalog." >}} +{{< /cards >}} diff --git a/content/docs/mcp/publish.md b/content/docs/mcp/publish.md deleted file mode 100644 index f742a38..0000000 --- a/content/docs/mcp/publish.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: Publish -weight: 20 -description: "Add an MCP server to the registry catalog. " ---- - -Build your MCP server image and push it to agentregistry so that you can start sharing the MCP server with other teams and deploying it to any environment. - -## About publishing MCP servers - -Agentregistry serves as a catalog for your AI artifacts, including agents, skills, and MCP servers. To control which images you want to make available to your teams, you can use the publishing capability in agentregistry. If an image is published, a reference to its container image location is stored in agentregistry. This allows teams to quickly discover approved MCP servers and deploy them from the registry. - -Before you can publish an image reference, you must first build the image. Agentregistry provides the following options for building your MCP server images: - -* **Build the image locally**. This option assumes that you want to build the MCP server image on your local machine only, such as for local test setups. The image is not pushed to your container registry. While you can still create a catalog entry for the MCP server image in agentregistry by using the `arctl mcp publish` command, you cannot deploy the image to a Kubernetes cluster, unless you manually load the image to your cluster. -* **Build and push**: This process allows you to build the MCP server image on your local machine and push it to your container registry. Note that this option requires you to be logged into the container registry that you want to use. - -For testing purposes, the instructions in this guide assume that you do not want to use agentregistry to push the image to your container registry. - - -## Before you begin - -1. Follow the [Get started](/docs/quickstart/) guide to set up agentregistry and start the agentregistry daemon. -2. [Create an MCP server](/docs/mcp/create/). - -## Publish the server - -1. If you have not done so yet, build the MCP server image on your local machine. - ```sh - arctl mcp build my-mcp-server --image my-mcp-server - ``` - - > [!TIP] - > To also use agentregistry to push the image to your container registry, include the `--push` option and set the `--docker-url` to your container registry address. You can also set the platform, for which you want to build the image, such as `linux/amd64` by using the `--platform` option. For more information, see the [arctl mcp publish](/docs/reference/cli/arctl-mcp-publish/) command. Make sure that you are logged in to your container registry before you run the command. - - Example output: - ```console - Building Docker image for python project... - #0 building with "desktop-linux" instance using docker driver - - #1 [internal] load build definition from Dockerfile - #1 transferring dockerfile: 1.84kB 0.0s done - #1 DONE 0.1s - - #2 [internal] load metadata for ghcr.io/astral-sh/uv:latest - #2 ... - - #3 [auth] library/python:pull token for registry-1.docker.io - ... - #24 unpacking to docker.io/library/my-mcp-server:0.1.0 0.9s done - #24 DONE 3.1s - ✓ Successfully built Docker image: my-mcp-server:0.1.0 - ``` - -2. Publish the image to agentregistry. The following command builds and tags the MCP server image as `docker.io/user/my-mcp-server:0.1.0` and creates a catalog entry for the server in agentregistry. The catalog entry assumes that the image is located in the `docker.io/user` image registry. Note that `docker.io/user` is a dummy container registry address that is used for testing purposes only. - ```sh - arctl mcp publish my-mcp-server \ - --type oci \ - --package-id my-mcp-server - ``` - - Example output: - ```console - Author not specified, defaulting to 'user' - Publishing MCP server: user/my-mcp-server (v0.1.0) - ✓ Published: user/my-mcp-server (v0.1.0) - ``` - -2. List the MCP server image references in your registry. Verify that you see the `my-mcp-server` MCP server image that you just published. - ```sh - arctl mcp list - ``` - - Example output: - ``` - NAME VERSION TYPE DEPLOYED UPDATED - user/my-mcp-server 0.1.0 oci False 37s - ``` - -3. Optional: Open the [agentregistry UI](http://localhost:12121) and go to the **Servers** view. Verify that you can see your MCP server image. - {{< reuse-image src="img/ar-list-server.png" >}} - {{< reuse-image-dark srcDark="img/ar-list-server-dark.png" >}} - - - - -## Cleanup - -To delete an MCP server from agentregistry, use the `arctl mcp delete` command. - -```sh -arctl mcp delete user/my-mcp-server --version 0.1.0 -``` - -## Next - -- [Deploy your MCP server](/docs/mcp/deploy). -- [Add your MCP server to an agent](/docs/agents/mcp/). diff --git a/content/docs/mcp/remote.md b/content/docs/mcp/remote.md new file mode 100644 index 0000000..a8edf87 --- /dev/null +++ b/content/docs/mcp/remote.md @@ -0,0 +1,70 @@ +--- +title: Register remote MCP servers +weight: 20 +description: Add an existing remote MCP server to the agentregistry catalog so that agents can discover and use it. +--- + +If you have an MCP server that is already running at a public URL, you can register it in the agentregistry catalog by referencing its URL in an `MCPServer` definition. The registry stores the URL as a catalog entry and makes the server available to agents. Agentregistry does not deploy or manage the server lifecycle. + +## Before you begin + +1. Install agentregistry on [Kubernetes]({{< link path="/setup/kubernetes" >}}). +2. Make sure you have a running MCP server that is reachable at a public URL. + +## Register the remote MCP server + +The following example registers the [GitHub MCP server](https://github.com/github/github-mcp-server), which requires a [GitHub Personal Access Token (PAT)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) for authentication. + +1. Save your GitHub Personal Access Token in an environment variable. + ```sh + export GH_PATH= + ``` + +2. Create a registry catalog entry for your remote MCP server. + ```yaml + arctl apply -f - <}} +{{< card link="/docs/agents/mcp/" title="Add to an agent" description="Wire your remote MCP server into an agent." >}} +{{< /cards >}} diff --git a/content/docs/mcp/tools.md b/content/docs/mcp/tools.md deleted file mode 100644 index e2f7b14..0000000 --- a/content/docs/mcp/tools.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Add tools -weight: 15 -description: "Add tools to your MCP server." ---- - -Add tools to your MCP server. - -## Before you begin - -1. Follow the [Get started](/docs/quickstart/) guide to set up agentregistry and start the agentregistry daemon. -2. Install [`uv`](https://docs.astral.sh/uv/getting-started/installation/). - -## Add tools - -1. If you have not done so yet, create an MCP server. Enter an optional description, author name, and email, or skip these by pressing the return key. - - The following command creates a `my-mcp-server` FastMCP server with an echo tool. When you run the command, a `my-mcp-server` directory is created on your local machine that contains the scaffold for your MCP server. - ```sh - arctl mcp init python my-mcp-server - ``` - -2. Create a scaffold for an `add_number` tool. The following command creates an `add_number.py` file in the `my-mcp-server` project. - ```sh - arctl mcp add-tool add_number --project-dir my-mcp-server - ``` - -3. Review the `add_number` tool scaffold that was created for you. - ```sh - nano my-mcp-server/src/tools/add_number.py - ``` - -4. Add the following code snippet to create the `add_number` tool. The code takes two integer numbers and returns the sum of both integers to the user. - ```python - @mcp.tool() - def add_numbers(a: float, b: float) -> str: - """Add two numbers together and return the result. - - Args: - a: The first number to add. - b: The second number to add. - - Returns: - A string representing the sum of the two numbers. - """ - # Optional: Get config if you want to control formatting/units - config = get_tool_config("add_numbers") - unit = config.get("unit", "") - - result = a + b - - return int(a + b) - ``` - -5. Re-build the MCP server image. - ```sh - arctl mcp build my-mcp-server --image my-mcp-server - ``` - -6. Run the MCP server on your local machine and note the MCP server URL that the server is exposed on. - ```sh - arctl mcp run my-mcp-server - ``` - - Example output: - ```console - Running local MCP server: my-mcp-server (version 0.1.0) - Using Docker image: my-mcp-server:0.1.0 - - MCP Server URL: http://localhost:57196/mcp - - Press CTRL+C to stop the server... - - 2026-01-27 22:12:40,261 - INFO - Loaded tool module: echo - 2026-01-27 22:12:40,261 - INFO - 📦 Successfully loaded 1 tools - 2026-01-27 22:12:40,647 - INFO - HTTP Request: GET https://pypi.org/pypi/fastmcp/json "HTTP/1.1 200 OK" - ... - ``` - -7. Open the MCP inspector tool. - ```sh - npx modelcontextprotocol/inspector#0.18.0 - ``` - -8. Connect to your MCP server. Enter the following details. - * Transport type: Select **Streamable HTTP**. - * URL: The MCP server URL that you retrieved earlier, such as `http://localhost:57196/mcp`. - * Click **Connect**. - -9. Go to the **Tools** tab and verify that you see the newly added `add_number` tool. Try out the tool by entering two integer numbers, such as 5 and 3. Then, click **Run Tool**. Verify that the sum of both numbers is returned. - {{< reuse-image src="img/mcp-add-tool.png" >}} - {{< reuse-image-dark srcDark="img/mcp-add-tool-dark.png" >}} - - -## Next - -[Publish your MCP server image to agentregistry](/docs/mcp/publish/). - - diff --git a/content/docs/operations/database.md b/content/docs/operations/database.md index 7975efb..2856d8d 100644 --- a/content/docs/operations/database.md +++ b/content/docs/operations/database.md @@ -10,8 +10,8 @@ For production environments, replace the bundled database with an external Postg ## Before you begin -- Creata or use an existing external PostgreSQL instance (version 14 or later) that is reachable from your agentregistry installation. For example, you can create an [Amazon RDS instance](https://aws.amazon.com/rds/resources/) -- Install agentregistry on [Docker]({{< link path="/setup/docker" >}}) or [Kubernetes]({{< link path="/setup/kubernetes" >}}) guide. +1. Creata or use an existing external PostgreSQL instance (version 14 or later) that is reachable from your agentregistry installation. For example, you can create an [Amazon RDS instance](https://aws.amazon.com/rds/resources/) +2. Install agentregistry on [Kubernetes]({{< link path="/setup/kubernetes" >}}). ## Step 1: Create the agentregistry database @@ -35,71 +35,6 @@ For production environments, replace the bundled database with an external Postg ## Step 2: Configure agentregistry -Configure agentregistry to use your external PostgreSQL instance. The setup varies depending on how you installed agentregistry on [Docker](#docker) or [Kubernetes](#kubernetes). - -### Docker - -1. Open `agentregistry-compose.yml` file. - ```sh - nano agentregistry-compose.yml - ``` - -2. Make the following changes. - 1. Remove the `postgres` service block entirely. - 2. Remove the `postgres_data` volume. - 3. Update the `AGENT_REGISTRY_DATABASE_URL` in the `agentregistry` service to point at your external database. - 4. Remove the `depends_on` condition that references the bundled postgres service. - - The updated `agentregistry` service looks similar to the following: - - ```yaml - services: - agentregistry: - image: ghcr.io/agentregistry-dev/agentregistry/server:${VERSION} - container_name: agentregistry-server - entrypoint: - - /bin/sh - - -c - - | - if [ -f /root/.kube/config.orig ]; then - mkdir -p /root/.kube - sed -E \ - -e 's|https://127\.0\.0\.1|https://host.docker.internal|g' \ - -e 's|https://localhost|https://host.docker.internal|g' \ - -e 's|certificate-authority-data:.*|insecure-skip-tls-verify: true|g' \ - /root/.kube/config.orig > /root/.kube/config - fi - exec /app/bin/arctl-server - environment: - AGENT_REGISTRY_DATABASE_URL: "postgres://user:password@your-pg-host:5432/agentregistry?sslmode=require" - AGENT_REGISTRY_SERVER_ADDRESS: ":8080" - AGENT_REGISTRY_ENABLE_REGISTRY_VALIDATION: "false" - AGENT_REGISTRY_MCP_PORT: "31313" - KUBECONFIG: "/root/.kube/config" - ports: - - "12121:8080" - - "31313:31313" - ... - ``` - -3. Restart agentregistry. - ```sh - docker compose -f agentregistry-compose.yml down - docker compose -f agentregistry-compose.yml up -d --wait - ``` - -4. Check the server logs for successful migration messages. - ```sh - docker compose -f agentregistry-compose.yml logs agentregistry | grep "migration" - ``` - - Example output: - ```console - {"time":"...","level":"info","msg":"all migrations applied successfully","component":"database.migrate"} - ``` - -### Kubernetes - 1. Store the database connection string in a Kubernetes Secret. The registry server reads the connection string from this Secret at startup. The connection string can be provided in two formats: diff --git a/content/docs/plugins/_index.txt b/content/docs/plugins/_index.txt new file mode 100644 index 0000000..4d33a80 --- /dev/null +++ b/content/docs/plugins/_index.txt @@ -0,0 +1,5 @@ +--- +title: Plugins +weight: 65 +description: "Publish and manage versioned plugin bundles with agentregistry." +--- diff --git a/content/docs/plugins/marketplace.txt b/content/docs/plugins/marketplace.txt new file mode 100644 index 0000000..99f25ca --- /dev/null +++ b/content/docs/plugins/marketplace.txt @@ -0,0 +1,84 @@ +--- +title: Use as a plugin marketplace +weight: 20 +description: "Expose the agentregistry plugin catalog as a private Claude Code plugin marketplace." +--- + +Agentregistry can serve its plugin catalog as a Claude Code-compatible plugin marketplace. When enabled, Claude Code and other AI coding assistants can browse and install plugins directly from your private registry, without going through a public marketplace. + +The registry exposes a read-only `marketplace.json` endpoint at: + +``` +GET http://localhost:12121/plugin-marketplace/marketplace.json +``` + +Only plugins that are fully resolved (the registry controller has pinned their git source and scanned their bundle) appear in the marketplace response. Plugins that are still resolving or failed to resolve are silently omitted. + +## Before you begin + +- Publish at least one plugin to the registry. See [Publish a plugin]({{< link path="/plugins/publish" >}}). +- Wait for the plugin controller to resolve the plugin's git source. Check the status with `arctl get plugin -o yaml` and look for `Ready: "True"` under `status.conditions`. + +## Enable the marketplace endpoint + +The marketplace endpoint is off by default. Enable it by setting the `PLUGIN_MARKETPLACE_COMPAT_ENABLED` environment variable to `true` on the registry server. + +{{< tabs >}} +{{% tab name="Docker" %}} + +Add the environment variable to the `agentregistry` service in your `docker-compose.yml`. + +```yaml +services: + agentregistry: + environment: + PLUGIN_MARKETPLACE_COMPAT_ENABLED: "true" +``` + +Then restart the service. + +```sh +docker compose up -d agentregistry +``` + +{{% /tab %}} +{{% tab name="Kubernetes" %}} + +Pass the environment variable as an extra env var in your Helm upgrade command. + +```sh +helm upgrade -i agentregistry oci://ghcr.io/agentregistry-dev/agentregistry/charts/agentregistry \ + --namespace agentregistry \ + --reuse-values \ + --set extraEnvVars[0].name=PLUGIN_MARKETPLACE_COMPAT_ENABLED \ + --set extraEnvVars[0].value=true +``` + +{{% /tab %}} +{{< /tabs >}} + +## Register the marketplace in Claude Code + +Once the endpoint is enabled, register the registry as a plugin marketplace source in Claude Code. + +```sh +claude plugin marketplace add http://localhost:12121/plugin-marketplace/marketplace.json +``` + +Claude Code fetches the `marketplace.json` from the registry and adds it as a private marketplace source. You can then browse and install plugins from your catalog. + +## Verify the connection + +List the available plugins in Claude Code to confirm the marketplace is connected. + +```sh +claude plugin list +``` + +The output includes plugins from your agentregistry catalog alongside any other marketplace sources you have configured. + +## Notes + +- Plugin names in the marketplace are namespaced as `namespace.plugin-name` (for example, `default.my-plugin`) to avoid collisions across namespaces. +- Only git-sourced plugins appear in the marketplace. OCI-sourced plugins are not included in the `marketplace.json` format. +- The endpoint is unauthenticated in the open source release. Enable it only on registries that are accessible to trusted users. diff --git a/content/docs/plugins/publish.txt b/content/docs/plugins/publish.txt new file mode 100644 index 0000000..88d8647 --- /dev/null +++ b/content/docs/plugins/publish.txt @@ -0,0 +1,98 @@ +--- +title: Publish a plugin +weight: 10 +description: "Register a plugin bundle from a git repository in the agentregistry catalog." +--- + +## About plugins + +A plugin is a versioned bundle of agent capabilities, including skills, MCP server declarations, lifecycle hooks, and sub-agents that follows the [Claude Code plugin format](https://code.claude.com/docs/en/plugins). You publish a plugin by registering a pointer to its git repository. The registry controller resolves the pointer to a concrete commit, scans the bundle, and records the plugin's inventory and manifest in the catalog automatically. + +The registry does not store the bundle itself. It stores the resolved source reference and the scanned metadata. + +## Before you begin + +1. Install agentregistry on [Kubernetes]({{< link path="/setup/kubernetes" >}}). + + > [!NOTE] + > The plugin controller requires `git` to clone and scan the plugin bundle. The agentregistry Docker image does not include `git`, so publishing plugins is not supported with the Docker install. + +2. Have your plugin repository hosted on GitHub or GitLab. + +## Publish a plugin + +1. Create a plugin definition YAML file that points to your plugin's git repository. Use `subfolder` if your plugin lives in a subdirectory of a monorepo. + + ```sh + cat > my-plugin.yaml << 'EOF' + apiVersion: ar.dev/v1alpha1 + kind: Plugin + metadata: + name: my-plugin + tag: v1.0.0 + spec: + title: My Plugin + description: A plugin that adds code review skills and hooks. + harnesses: + - claude-code + source: + type: git + git: + repository: + url: https://github.com/my-org/my-plugin + commit: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2 + subfolder: packages/my-plugin # optional: omit if not a monorepo + EOF + ``` + +2. Apply the plugin definition to agentregistry. + + ```sh + arctl apply -f my-plugin.yaml + ``` + + Example output: + ```console + plugin.agentregistry.dev/my-plugin:v1.0.0 applied + ``` + +3. Verify the plugin was registered and check its status. The registry controller clones the repository and scans the bundle in the background, so the `Ready` condition may show `Progressing` briefly. + + ```sh + arctl get plugin my-plugin + ``` + + Example output: + ```console + NAME TAG DESCRIPTION + my-plugin v1.0.0 A plugin that adds code review skills and hooks. + ``` + + To see the full resolved status, including the scanned inventory: + + ```sh + arctl get plugin my-plugin -o yaml + ``` + +4. List all plugins in the catalog. + + ```sh + arctl get plugins + ``` + + Example output: + ```console + NAME TAG DESCRIPTION + my-plugin v1.0.0 A plugin that adds code review skills and hooks. + ``` + +> [!NOTE] +> Plugin management is available through the REST API and `arctl` CLI. A UI for plugins is not yet available in the open source release. + +## Cleanup + +To delete a plugin version from agentregistry, use the `arctl delete` command. + +```sh +arctl delete plugin my-plugin:v1.0.0 +``` diff --git a/content/docs/prompts/publish.md b/content/docs/prompts/publish.md index fffd28c..cd176a8 100644 --- a/content/docs/prompts/publish.md +++ b/content/docs/prompts/publish.md @@ -1,135 +1,95 @@ --- -title: Create and publish +title: Publish a prompt weight: 10 description: "Create a prompt and publish it to the registry catalog." --- -Quickly create a prompt and publish it to agentregistry. - ## About prompts Prompts are reusable, versioned text strings that serve as system instructions for agents. Instead of hardcoding instructions in agent code, you can publish prompts to agentregistry and reference them in your agent's `agent.yaml` file. When the agent runs, the prompt content is automatically resolved from the registry and used as the agent's instruction. -Prompts are plain text. You write the instruction content in a `.txt` file (or any text file) and publish it with a name and version. You can also use a YAML file for structured definitions. - ## Before you begin -Follow the [Get started](/docs/quickstart/) guide to set up agentregistry and start the agentregistry daemon. +Install agentregistry on [Kubernetes]({{< link path="/setup/kubernetes" >}}). ## Create a prompt -Write your prompt content to a text file. - -```sh -cat > code-review-prompt.txt << 'EOF' -You are an expert code reviewer. When reviewing code: -1. Check for bugs and logic errors -2. Identify security vulnerabilities -3. Suggest performance improvements -4. Ensure code follows best practices and is readable -5. Be constructive and specific in your feedback -EOF -``` - -## Publish the prompt - -1. Publish the prompt in agentregistry. You can pass the details in CLI flags or use a prompt definition YAML file. - {{< tabs >}} - {{% tab name="CLI flags" %}} - - Use the `arctl` CLI to define the details of your prompt, such as the name and version. - - Publish the prompt to agentregistry. The `--name` and `--version` flags are required when publishing from a text file. +1. Create a prompt by using the built-in scaffolding capability in agentregistry. ```sh - arctl prompt publish code-review-prompt.txt \ - --name code-review \ - --version 1.0.0 \ - --description "System prompt for code review agent" + arctl init prompt code-review \ + --description "System prompt for code review agent" \ + --content "$(cat <<'EOF' + You are an expert code reviewer. When reviewing code: + 1. Check for bugs and logic errors + 2. Identify security vulnerabilities + 3. Suggest performance improvements + 4. Ensure code follows best practices and is readable + 5. Be constructive and specific in your feedback + EOF + )" ``` - Example output: + Example output: ```console - Publishing prompt 'code-review' version 1.0.0 from: /Users/myuser/code-review-prompt.txt - ✓ Prompt 'code-review' version 1.0.0 published successfully! + 🚀 Next steps: + 1. Edit code-review.yaml (optional) + 2. Publish to the registry: + arctl apply -f code-review.yaml ``` - > [!NOTE] - > Use `--dry-run` to preview the prompt payload without publishing. For more information, see the [arctl prompt publish](/docs/reference/cli/arctl-prompt-publish/) command. - - {{% /tab %}} - {{% tab name="Prompt template" %}} - - For structured prompt definitions, you can use a YAML file. This lets you set all fields in one place instead of using CLI flags. - - 1. Create a YAML file with your prompt definition. - - ```sh - cat > my-prompt.yaml << 'EOF' - name: code-review - description: System prompt for code review agent - version: 2.0.0 - content: | - You are a senior code reviewer specializing in production systems. - Focus on: correctness, security, performance, and maintainability. - Always provide specific line references and actionable suggestions. - EOF - ``` - - 2. Publish the YAML file directly. Name and version are read from the file. - ```sh - arctl prompt publish my-prompt.yaml - ``` - - {{% /tab %}} - {{< /tabs >}} - -2. Verify the prompt was published. - +2. Review the prompt template that was created for you. You can optionally make changes to your template. ```sh - arctl prompt list + cat code-review.yaml ``` - Example output: + Example output: ```console - NAME VERSION DESCRIPTION - code-review 1.0.0 System prompt for code review agent + apiVersion: ar.dev/v1alpha1 + kind: Prompt + metadata: + name: code-review + spec: + content: |- + You are an expert code reviewer. When reviewing code: + 1. Check for bugs and logic errors + 2. Identify security vulnerabilities + 3. Suggest performance improvements + 4. Ensure code follows best practices and is readable + 5. Be constructive and specific in your feedback + description: System prompt for code review agent ``` -3. View the prompt details. +## Publish the prompt +1. Publish the prompt in the registry catalog. ```sh - arctl prompt show code-review + arctl apply -f code-review.yaml ``` - Example output: + Example output: ```console - PROPERTY VALUE - Name code-review - Description System prompt for code review agent - Version 1.0.0 - Status active - Content You are an expert code reviewer. When reviewing code: - 1. Check for bugs and logic errors - 2. Identify security vulnerabilities - 3. Suggest performance improvements - 4. Ensure code follows best practices - ... + ✓ Prompt/code-review (latest) created ``` -4. Optional: Open the [agentregistry UI](http://localhost:12121) and go to the **Prompts** view. Verify that you can see your prompt. - {{< reuse-image src="img/ar-publish-prompt.png" >}} - {{< reuse-image-dark srcDark="img/ar-publish-prompt-dark.png" >}} - +2. Verify that the prompt is created. + ```sh + arctl get prompts + ``` -## Next + Example output: + ```console + NAME TAG DESCRIPTION + code-review latest System prompt for code review agent + ``` -[Add your prompt to an agent](/docs/agents/prompt). +3. Optional: Open the [agentregistry UI](http://localhost:12121) and go to the **Catalog** > **Prompts** view. Verify that you can see your prompt. + {{< reuse-image src="img/ar-publish-prompt.png" srcDark="img/ar-publish-prompt-dark.png" >}} ## Cleanup -To delete a prompt version from agentregistry, use the `arctl prompt delete` command. +To delete a prompt from agentregistry, use the `arctl delete prompt` command. ```sh -arctl prompt delete code-review --version 1.0.0 +arctl delete prompt code-review ``` diff --git a/content/docs/quickstart.md b/content/docs/quickstart.md index 1d3968f..0cdf147 100644 --- a/content/docs/quickstart.md +++ b/content/docs/quickstart.md @@ -1,39 +1,40 @@ --- title: Get started weight: 5 -description: "Get started with agentregistry." +description: Install agentregistry in a Kubernetes cluster by using the Helm package manager. --- -Agentregistry is an open source, secure, and centralized AI artifact catalog that helps you build, package, publish, discover, and govern Docker images for AI artifacts, including agents, skills, and MCP servers that are spread across multiple container registries and GitHub repositories. It provides a centralized view of the images you allow your teams to share and deploy into their environments. +Agentregistry is an open source, centralized AI artifact catalog that helps you build, package, publish, and discover AI artifacts, including agents, skills, MCP servers, prompts, and plugins. It provides a single source of truth for the AI building blocks your teams share and deploy. -Want to learn more about agentregistry? Check out the [About](/docs/about/) section. - -## About this guide - -In this guide, you learn how to install agentregistry for local development with Docker. This approach is useful if you want to run agentregistry from your local machine, an on-prem environment, or a VM. Agentregistry is spun up by using Docker containers and you can use this installation to deploy AI artifacts to your local environment and Kubernetes clusters. +> [!TIP] +> Want to learn more about agentregistry? Check out the [About agentregistry]({{< link path="/about/" >}}) section. -To install agentregistry in a Kubernetes cluster instead, see the [Install in Kubernetes](/docs/setup/kubernetes/) guide. ## Before you begin -1. Set up and start a Docker Engine on your local machine, such as [Docker Desktop](https://docs.docker.com/desktop/). Agentregistry uses Docker compose to build Docker images and spin up AI artifacts. -2. If you want to use agentregistry to push images to your Docker image registry, log in to your registry. For example, you might use Dockerhub (`docker.io`) or GitHub Container Registry (`ghcr.io`) as your image registry. Note that this step is required if you want to use agentregistry to build and push images to your registry. For local testing, you can skip this step and instead build images locally only. +1. Install the following CLIs: + - [`kubectl`](https://kubernetes.io/docs/tasks/tools/) + - [Helm](https://helm.sh/docs/intro/install/) v3 or later +2. Create or use an existing Kubernetes cluster. For local test setup, you can use [Kind](https://kind.sigs.k8s.io/). ```sh - docker login + kind create cluster ``` -## Setup +## Install agentregistry -{{< reuse "ar-docs/setup-docker.md" >}} +{{< reuse "ar-docs/kubernetes.md" >}} -## Next +## Install the `arctl` CLI -With agentregistry up and running, you can explore how to build, publish, and deploy AI artifacts. Check out the following guides for more information: +{{< reuse "ar-docs/arctl.md" >}} -* [**Agents**](/docs/agents/): Explore how to build, run, and publish Docker images for agents. -* [**MCP servers**](/docs/mcp/): Create and run MCP tool servers, add tools, and publish them as Docker images in agentregistry. -* [**Skills**](/docs/skills/): Build and publish skills that you can add to your agents. -* [**Prompts**](/docs/prompts/): Build and publish prompts that you can add to your agents. +## Next steps -> [!TIP] -> To stop the registry while preserving its data, run `docker compose -f agentregistry-compose.yml down`. If you want to also remove the bundled PostgreSQL volume, add the `-v` flag. +With agentregistry up and running, start adding AI artifacts to build out your AI artifact catalog. + +{{< cards >}} +{{< card link="/docs/agents/" title="Agents" description="Build, run, and publish agents." >}} +{{< card link="/docs/mcp/" title="MCP servers" description="Create and run MCP tool servers and publish them to the catalog." >}} +{{< card link="/docs/skills/" title="Skills" description="Build and publish skills that you can add to your agents." >}} +{{< card link="/docs/prompts/" title="Prompts" description="Build and publish prompts that you can add to your agents." >}} +{{< /cards >}} diff --git a/content/docs/setup/docker.md b/content/docs/setup/docker.md deleted file mode 100644 index c1fa0a8..0000000 --- a/content/docs/setup/docker.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Install with Docker -weight: 10 -description: "Install agentregistry for local development with Docker to build, publish, and deploy AI artifacts." ---- - -Use this guide to install agentregistry for local development with Docker. This approach is useful if you want to run agentregistry from your local machine, an on-prem environment, or a VM. Agentregistry is spun up using Docker containers and you can use this installation to build, publish, and deploy AI artifacts to your local environment and Kubernetes clusters. - -To install agentregistry in a Kubernetes cluster instead, see the [Install in Kubernetes](/docs/setup/kubernetes/) guide. - -## Before you begin - -1. Set up and start a Docker Engine on your local machine, such as [Docker Desktop](https://docs.docker.com/desktop/). Agentregistry uses Docker Compose to build Docker images and spin up AI artifacts. -2. If you want to use agentregistry to push images to a Docker image registry, log in to your registry. For example, you might use Docker Hub (`docker.io`) or GitHub Container Registry (`ghcr.io`). This step is only required if you want to build and push images to a remote registry. For local testing, you can skip this step and build images locally only. - ```sh - docker login - ``` - -## Install - -{{< reuse "ar-docs/setup-docker.md" >}} - -## Next steps - -With agentregistry up and running, you can explore how to build, publish, and deploy AI artifacts: - -* [**Agents**](/docs/agents/): Build, run, and publish Docker images for agents. -* [**MCP servers**](/docs/mcp/): Create and run MCP tool servers, add tools, and publish them as Docker images. -* [**Skills**](/docs/skills/): Build and publish skills that you can add to your agents. -* [**Prompts**](/docs/prompts/): Build and publish prompts that you can add to your agents. -* [**BYO PostgreSQL database**]({{< link path="/operations/database/" >}}): Replace the bundled PostgreSQL instance with an external database for production use. -* [**Connect AI development tools**]({{< link path="/setup/mcp-client/" >}}): Connect Claude Code, Cursor, VS Code, or Kiro to the registry catalog. diff --git a/content/docs/setup/kubernetes.md b/content/docs/setup/kubernetes.md index 98058fb..a7b3e3c 100644 --- a/content/docs/setup/kubernetes.md +++ b/content/docs/setup/kubernetes.md @@ -1,14 +1,11 @@ --- title: Install on Kubernetes -weight: 20 +weight: 10 description: "Install agentregistry in a Kubernetes cluster with Helm for shared team access to a central artifact registry." --- Use this guide to install agentregistry in a Kubernetes cluster by using Helm. This approach is useful for team environments where multiple developers need shared access to a central artifact registry. -> [!NOTE] -> If you install agentregistry in a Kubernetes cluster, you cannot deploy AI artifacts to a local environment. To deploy them to a local environment, you must [install agentregistry locally with Docker](/docs/setup/docker/). - ## Before you begin Make sure you have the following tools installed: @@ -18,58 +15,11 @@ Make sure you have the following tools installed: ## Install with Helm -The Helm chart includes a bundled PostgreSQL instance for development and evaluation. For production, [bring your own PostgreSQL instance]({{< link path="/operations/database/" >}}) instead. - -1. Install agentregistry with the bundled PostgreSQL instance. - ```sh - helm upgrade -i agentregistry oci://ghcr.io/agentregistry-dev/agentregistry/charts/agentregistry \ - --namespace agentregistry \ - --create-namespace - ``` - - > [!WARNING] - > The bundled PostgreSQL instance is for development and evaluation only. Data is lost if the PostgreSQL pod is restarted or rescheduled. For production, use an external PostgreSQL instance instead. See the [BYO PostgreSQL database]({{< link path="/operations/database/" >}}) guide. - -2. Verify that the agentregistry and PostgreSQL pods are up and running. - ```sh - kubectl get pods -n agentregistry - ``` - - Example output: - ```console - NAME READY STATUS RESTARTS AGE - agentregistry-c46b8bd98-hvnzf 1/1 Running 0 45s - gentregistry-postgresql-9858cbcbf-tk7p9 1/1 Running 0 45s - ``` - -3. Port-forward the agentregistry service to access the UI and API from your local machine. - ```sh - kubectl port-forward -n agentregistry svc/agentregistry 12121:12121 - ``` - -4. Optional: If you want to connect AI development tools to the registry MCP server, port-forward the MCP port in a separate terminal. - ```sh - kubectl port-forward -n agentregistry svc/agentregistry 31313:31313 - ``` - -5. [Open the agentregistry UI](http://localhost:12121/) in your browser. +{{< reuse "ar-docs/kubernetes.md" >}} ### Install the `arctl` CLI -1. Install the agentregistry `arctl` binary on your local machine. - ```sh - curl -fsSL https://raw.githubusercontent.com/agentregistry-dev/agentregistry/main/scripts/get-arctl | bash - - export PATH="/usr/local/bin:$PATH" - ``` - -2. Verify that the CLI is installed correctly. - ```sh - arctl version - ``` - -> [!TIP] -> By default, `arctl` connects to `http://localhost:12121`. If your agentregistry instance is exposed at a different address, set the `ARCTL_API_BASE_URL` environment variable or pass `--registry-url` on each command. For example, to set the environment variable, use `export ARCTL_API_BASE_URL=http://:12121`. +{{< reuse "ar-docs/arctl.md" >}} ## Next steps diff --git a/content/docs/setup/mcp-client.md b/content/docs/setup/mcp-client.md index 7ef1659..060fe4e 100644 --- a/content/docs/setup/mcp-client.md +++ b/content/docs/setup/mcp-client.md @@ -39,7 +39,7 @@ The following MCP clients are supported out of the box. ## Before you begin -Install agentregistry on [Docker]({{< link path="/setup/docker" >}}) or [Kubernetes]({{< link path="/setup/kubernetes" >}}). +Install agentregistry on [Kubernetes]({{< link path="/setup/kubernetes" >}}). ## Connect to the MCP server diff --git a/content/docs/setup/runtime.md b/content/docs/setup/runtime.md new file mode 100644 index 0000000..b7d6f2a --- /dev/null +++ b/content/docs/setup/runtime.md @@ -0,0 +1,64 @@ +--- +title: Connect a runtime +weight: 20 +description: "Connect agentregistry to a kagent runtime to deploy agents and MCP servers to your Kubernetes cluster." +--- + +[Kagent](https://kagent.dev) is an open source, Kubernetes-native AI runtime. It extends Kubernetes with custom resources for agents and MCP servers, letting you manage AI workloads the same way you manage any other Kubernetes application. Agentregistry uses kagent to deploy and manage agents and MCP servers as pods in your cluster via a pre-configured `kubernetes-default` runtime. + +The steps in this guide walk you through how to install the kagent open source project so that you can use it as a deployment runtime in agentregistry. + +## Before you begin + +1. Install agentregistry on [Kubernetes]({{< link path="/quickstart/" >}}). +2. Get an OpenAI API key from [platform.openai.com](https://platform.openai.com/api-keys). Kagent requires an LLM provider to power the agents it runs. The minimal profile uses OpenAI by default. + +## Step 1: Install kagent + +1. Save your OpenAI API key in an environment variable. + ```sh + export OPENAI_API_KEY= + ``` + +2. Install kagent with the minimal profile. + ```sh + kagent install --profile minimal + ``` + +3. Verify that the kagent pods are running. + ```sh + kubectl get pods -n kagent + ``` + + Example output: + ```console + NAME READY STATUS RESTARTS AGE + kagent-controller-5bc5964cbb-rh5vw 1/1 Running 0 5m25s + kagent-grafana-mcp-546d857557-lvgq5 1/1 Running 0 5m25s + kagent-kmcp-controller-manager-b8dd8ccfd-5fjds 1/1 Running 0 5m25s + kagent-querydoc-84d8dcfd-9lbzw 1/1 Running 0 5m25s + kagent-tools-7f477dcb7b-q866j 1/1 Running 0 5m25s + kagent-ui-756689ffb4-wfbzw 1/1 Running 0 5m25s + ``` + +## Step 2: Verify the runtime + +Agentregistry creates a `kubernetes-default` runtime during the installation. Confirm that it is listed and that the kagent pods are ready before deploying. + +1. List the runtimes in agentregistry. + ```sh + arctl get runtimes + ``` + + Example output: + ```console + NAME TYPE + kubernetes-default Kubernetes + ``` + +## Next steps + +{{< cards >}} +{{< card link="/docs/mcp/local/deploy/" title="Deploy an MCP server" description="Deploy a published MCP server to your kagent runtime." >}} +{{< card link="/docs/agents/deploy/kubernetes/" title="Deploy an agent" description="Deploy a published agent to your kagent runtime." >}} +{{< /cards >}} diff --git a/content/docs/skills/create.md b/content/docs/skills/create.md deleted file mode 100644 index 241b0d8..0000000 --- a/content/docs/skills/create.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Create -weight: 10 -description: Create an agent skill using the built-in skill scaffold. ---- - -Quickly create an agent skill using the built-in skill scaffold. - -## Before you begin - -Follow the [Get started](/docs/quickstart/) guide to set up agentregistry and start the agentregistry daemon. - -## Create a skill - -Agentregistry comes with a built-in skill template that you can use to quickly create skills or customize them to your needs. - -1. Create a skill scaffold. - - The following command creates a `myskill` directory that includes a starter skill with a Python script and supporting files. - ```sh - arctl skill init myskill - ``` - -2. Explore the skill scaffold that was created for you. You can optionally make changes to the files to customize your skill further. - ``` - ls myskill - ``` - - Example output: - ``` - assets Dockerfile LICENSE.txt references scripts SKILL.md - ``` - - | File | Description | - | -- | -- | - | `assets` | Directory containing static assets such as images, files, or other resources used by the skill. | - | `Dockerfile` | The Dockerfile to spin up and run your skill in a containerized environment. | - | `LICENSE.txt` | License file containing the license information for your skill. | - | `references` | Directory containing reference documentation, links, or additional resources related to the skill. | - | `scripts` | Directory containing helper scripts for building, testing, or running the skill. | - | `SKILL.md` | The skill definition file with YAML frontmatter that describes the skill, its capabilities, and metadata. This file is required for publishing the skill to agentregistry. | - -## The SKILL.md file - -The `SKILL.md` file is the core definition of your skill. It uses YAML frontmatter to define metadata, followed by markdown content that describes the skill's capabilities and usage instructions. - -```markdown ---- -name: myskill -description: A brief description of what this skill does ---- -# My Skill - -Detailed instructions and documentation for the skill. -This content is included when the skill is used by an agent. -``` - -The frontmatter fields: - -| Field | Description | -| -- | -- | -| `name` | The skill name. Used as the identifier when publishing. If omitted, the directory name is used. | -| `description` | A short description of the skill's purpose. Displayed in the registry listing. | - -## Next steps - -- [Build and publish the skill](/docs/skills/publish/). -- [Pull a skill](/docs/skills/pull/) from the registry to use it locally. diff --git a/content/docs/skills/publish.md b/content/docs/skills/publish.md index 488d4d6..5d0e27a 100644 --- a/content/docs/skills/publish.md +++ b/content/docs/skills/publish.md @@ -1,147 +1,168 @@ --- -title: Publish -weight: 20 -description: "Publish skills to agentregistry so others can discover and pull them." +title: Create and publish a skill +weight: 10 +description: Scaffold a skill and publish it to the agentregistry catalog. --- -Publish skills to agentregistry so others can discover and pull them. +## About skills -## About publishing skills +A skill is a reusable instruction set or slash command for AI agents that you can store as a versioned artifact in the catalog. Instead of sharing skill files ad-hoc, developers publish skills to the registry with a version tag. When you iterate on a skill, you publish a new version so that consumers can pull the update at any time. -Agentregistry serves as a catalog for your AI artifacts, including agents, skills, and MCP servers. To control which images you want to make available to your teams, you can use the publishing capability in agentregistry. If a skill is published, a reference to its source (container image or GitHub repository) is stored in agentregistry. This allows teams to quickly discover approved skills and pull them from the registry. - -Agentregistry supports multiple publishing modes: - -* **From a local skill folder**: Reads metadata from a local `SKILL.md` file and publishes the skill with either a pre-built Docker image reference or a GitHub repository reference. -* **Direct registration**: Registers a skill by name with a GitHub repository or Docker image reference, without needing any local files. +Skills are defined in a markdown file named `SKILL.md`. The file uses YAML frontmatter for catalog metadata such as a name and description, followed by markdown content with the skill's instructions. ## Before you begin -1. Follow the [Get started](/docs/quickstart/) guide to set up agentregistry and start the agentregistry daemon. -2. If publishing from a local folder, [create a skill](/docs/skills/create/) first. +Install agentregistry on [Kubernetes]({{< link path="/setup/kubernetes" >}}). -## Build the skill (optional) +## Create a skill -If you want to publish your skill as a Docker image, build it first using the `arctl skill build` command: +Agentregistry comes with a built-in skill template that you can use to quickly scaffold a skill and customize it to your needs. -```sh -arctl skill build ./myskill --image docker.io/user/hello-world-template:v1.0.0 -``` +1. Create a skill scaffold. -To also push the image to your container registry, include the `--push` option: - -```sh -arctl skill build ./myskill --image docker.io/user/hello-world-template:v1.0.0 --push -``` - -> [!TIP] -> To also use agentregistry to push the image to your container registry, include the `--push` option. You can also set the platform, for which you want to build the image, such as `linux/amd64` by using the `--platform` option. For more information, see the [arctl mcp build](/docs/reference/cli/arctl-mcp-build/) command. Make sure that you are logged in to your container registry before you run the command. + The following command creates a `myskill` directory that includes a starter skill definition and supporting files. + ```sh + arctl init skill myskill + ``` -## Publish the skill + Example output: + ```console + ✓ Created skill: myskill -Review the different ways how you can publish a skill. + 🚀 Next steps: + 1. Edit myskill/SKILL.md and references/ (optional) + 2. Publish to the registry: + arctl apply -f myskill/skill.yaml + ``` -### Option 1: Publish with a Docker image (from local folder) +2. Explore the skill scaffold. -Use this option when you have a local skill folder with a `SKILL.md` file and have already built a Docker image using `arctl skill build`. + ```sh + ls myskill + ``` -```sh -arctl skill publish ./myskill \ - --docker-image docker.io/user/hello-world-template:v1.0.0 \ - --version 1.0.0 -``` + Example output: + ```console + assets LICENSE.txt references scripts SKILL.md skill.yaml + ``` -The skill name and description are read from the local `SKILL.md` file. The `--docker-image` flag specifies the pre-built Docker image to register. + | File | Description | + | --- | --- | + | `skill.yaml` | The v1alpha1 skill definition. Contains catalog metadata such as name, description, and version. Apply this file to publish the skill to the registry. | + | `SKILL.md` | The skill instruction content. This is the markdown text that agents receive when the skill is invoked. Edit this file to define what the skill does. | + | `assets/` | Directory for static assets such as images or files used by the skill. | + | `references/` | Directory for supporting reference documentation, links, or additional context for the skill. | + | `scripts/` | Directory for helper scripts, such as the starter `hello_world.py` example. | + | `LICENSE.txt` | License information for the skill. | -> [!TIP] -> To preview the registry entry without creating it, use the `--dry-run` flag. +3. Review the skill definition. This file describes that catalog entry that you want to create in the registry. Note that the scaffold does not include the reference to your git repository by default. You later update this skill definition to add your git reference. + ```sh + cat myskill/skill.yaml + ``` -### Option 2: Publish from a GitHub repository (with local folder) + Example output: + ```console + apiVersion: ar.dev/v1alpha1 + kind: Skill + metadata: + name: myskill + spec: + description: myskill skill + title: myskill + ``` -Use this option when you have the skill files locally but want to register a GitHub repository as the source instead of a Docker image. The skill metadata, such as the name and description, is read from the local `SKILL.md` file. +4. Review and optionally edit the `myskill/SKILL.md` file to define your skill's instructions. Use the frontmatter to set the catalog metadata, such as the name and description for the catalog entry in the UI, and the markdown body to define your skill. + ```sh + nano myskill/skill.md + ``` -```sh -arctl skill publish ./myskill \ - --github https://github.com/myorg/my-skills/tree/main/skills/myskill \ - --version 1.0.0 -``` + -Use this option to register a skill with a pre-built Docker image reference without needing any local files. +## Publish the skill -```sh -arctl skill publish my-docker-skill \ - --docker-image docker.io/myorg/my-skill:v1.0.0 \ - --version 1.0.0 \ - --description "A Docker-packaged skill" -``` +1. Publish the skill to agentregistry. + ```sh + arctl apply -f myskill/skill.yaml + ``` -In direct mode: -- The first argument is the **skill name** (not a folder path). -- `--docker-image` and `--version` are **required**. -- `--description` is optional. + Example output: + ```console + ✓ Skill/myskill (latest) created + ``` -> [!TIP] -> To preview the registry entry without creating it, use the `--dry-run` flag. + The skill controller resolves the branch to a concrete commit and records it in the `status.resolvedSource.commit` of your skill, so the registry always tracks exactly which revision is live. -## Verify the published skill +2. Verify that the skill was registered. -1. List the skill references in agentregistry. Verify that you see an entry for the skill that you just published. ```sh - arctl skill list + arctl get skills ``` Example output: - ``` - NAME TITLE VERSION TYPE SOURCE - hello-world-template 1.0.0 docker docker.io/user/hello-world-template:v1.0.0 + ```console + NAME TAG DESCRIPTION + myskill latest A reusable skill stored in git. ``` -2. Optional: Open the [agentregistry UI](http://localhost:12121) and go to the **Skills** view. Verify that you can see your skill. - {{< reuse-image src="img/ar-publish-skill.png" >}} - {{< reuse-image-dark srcDark="img/ar-publish-skill-dark.png" >}} +3. Optional: Open the [agentregistry UI](http://localhost:12121) and go to the **Skills** view. Verify that you can see your skill. + {{< reuse-image src="img/ar-publish-skill.svg" srcDark="img/ar-publish-skill-dark.svg" >}} ## Next steps -- [Add a skill to your agent](/docs/agents/skills/). -- [Pull a skill](/docs/skills/pull/) from the registry to use it locally. +{{< cards >}} +{{< card link="/docs/agents/skills/" title="Add a skill to an agent" description="Configure an agent to use a skill from the registry." >}} +{{< card link="/docs/skills/pull/" title="Pull a skill from the registry" description="Pull a skill from the registry to use it locally." >}} +{{< /cards >}} ## Cleanup -To delete a skill from agentregistry, use the `arctl skill delete` command. +To delete a skill from agentregistry, use the `arctl delete skill` command. ```sh -arctl skill delete hello-world-template --version 1.0.0 +arctl delete skill myskill ``` diff --git a/content/docs/skills/pull.md b/content/docs/skills/pull.md index 06218bb..86cdb04 100644 --- a/content/docs/skills/pull.md +++ b/content/docs/skills/pull.md @@ -4,57 +4,30 @@ weight: 30 description: "Pull a published skill from agentregistry and extract its contents to your local machine." --- -Pull a published skill from agentregistry and extract its contents to your local machine. - ## Before you begin -1. Follow the [Get started](/docs/quickstart/) guide to set up agentregistry and start the agentregistry daemon. -2. Ensure that the skill you want to pull is [published](/docs/skills/publish/) to agentregistry. - -## Pull a skill +1. Install agentregistry on [Kubernetes]({{< link path="/setup/kubernetes" >}}). +2. [Create and publish a skill]({{< link path="/skills/publish/" >}}) to the registry catalog. -Use the `arctl skill pull` command to download a skill from the registry and extract its contents locally. - -```sh -arctl skill pull -``` +## Pull a skill from the registry -By default, the skill is extracted to `./skills/`. You can specify a custom output directory: +Use the `arctl pull skill` command to download a skill from the registry and extract its contents locally. -```sh -arctl skill pull my-skill ./my-output-dir -``` +The `pull` command reads the skill's `spec.source.repository` setting from the registry and clones it locally by using a shallow clone (`--depth 1`). If a `subfolder` is set in the skill definition, only the files from that subdirectory are copied to the output directory. -## Specify a version +> [!NOTE] +> The `pull` command uses the source reference that you set in the `spec.source.repository` block, **not the commit** that was automatically pinned by the registry controller in the `status.resolvedSource.commit` field when you published the skill. If you published the skill without a specific commit ID, such as by only defining a branch and subfolder, the `pull` command fetches the current tip of that branch. To get a reproducible pull, publish the skill with a `commit` SHA instead of a branch. -If the skill has multiple versions published, use `--version` to specify which one to pull: +> [!TIP] +> By default the skill is pulled into the directory that you are currently in. To define a different directory, add the directory path to your command, such as `arctl pull skill myskill ./my-output-dir`. For other command options, see the [CLI reference]({{< link path="/reference/cli/arctl-pull/" >}}). ```sh -arctl skill pull my-skill --version 1.0.0 +arctl pull skill myskill ``` -If you don't specify a version: -- If only one version exists, it is selected automatically. -- If multiple versions exist, you are prompted to choose one. - -## How it works - -The `pull` command automatically detects the skill's source and handles extraction: - -- **Docker-packaged skills**: The container image is pulled, a temporary container is created, and the skill files are extracted from it. -- **GitHub-hosted skills**: The repository is cloned (using `--depth 1` for efficiency), and the relevant files are copied to the output directory. If the skill's GitHub URL includes a branch and subdirectory path, only the files from that subdirectory are extracted. - -In both cases, the skill files are placed in the output directory ready for use. - -## Example - -```sh -# Pull a skill to the default location (./skills/argocd-cli-setup) -arctl skill pull argocd-cli-setup - -# Pull a specific version to a custom directory -arctl skill pull argocd-cli-setup ./my-skills/argocd --version 1.0.0 - -# List available skills in the registry -arctl skill list +Example output: +```console +Cloning https://github.com/my-org/myrepo (branch main) into /my/current/path +(subfolder hint: agentregistry/myskill) +Pulled myskill ``` diff --git a/content/docs/ui.md b/content/docs/ui.md index e454b76..b444b27 100644 --- a/content/docs/ui.md +++ b/content/docs/ui.md @@ -23,7 +23,7 @@ The agentregistry UI comes with different built-in views that you can use to gai ### Catalog -The catalog view provides an overview of all discovered AI artifacts. This view allows you to publish artifacts to the registry so that they can be shared among teams or deployed to a local or Kubernetes environment. +The catalog view provides an overview of all discovered AI artifacts. This view allows you to publish artifacts to the registry so that they can be shared among teams or deployed to a Kubernetes environment. #### Servers diff --git a/hugo_stats.json b/hugo_stats.json index d690caf..c93a668 100644 --- a/hugo_stats.json +++ b/hugo_stats.json @@ -183,7 +183,6 @@ "hx:active:opacity-50", "hx:align-middle", "hx:appearance-none", - "hx:bg-amber-100", "hx:bg-black/[.05]", "hx:bg-blue-100", "hx:bg-green-100", @@ -193,7 +192,6 @@ "hx:block", "hx:border", "hx:border-0", - "hx:border-amber-200", "hx:border-b", "hx:border-b-2", "hx:border-black/5", @@ -218,7 +216,6 @@ "hx:contrast-more:text-gray-700", "hx:contrast-more:text-gray-800", "hx:cursor-pointer", - "hx:dark:bg-amber-900/30", "hx:dark:bg-blue-900/30", "hx:dark:bg-dark", "hx:dark:bg-dark/50", @@ -227,7 +224,6 @@ "hx:dark:bg-neutral-900", "hx:dark:bg-primary-300/10", "hx:dark:block", - "hx:dark:border-amber-200/30", "hx:dark:border-blue-200/30", "hx:dark:border-gray-100/20", "hx:dark:border-green-200/30", @@ -245,7 +241,6 @@ "hx:dark:hover:text-white", "hx:dark:placeholder:text-gray-400", "hx:dark:shadow-[0_-1px_0_rgba(255,255,255,.1)_inset]", - "hx:dark:text-amber-200", "hx:dark:text-blue-200", "hx:dark:text-gray-200", "hx:dark:text-gray-300", @@ -415,7 +410,6 @@ "hx:sticky", "hx:text-4xl", "hx:text-[10px]", - "hx:text-amber-900", "hx:text-base", "hx:text-blue-900", "hx:text-center", @@ -495,6 +489,7 @@ "sidebar-list-depth-0", "sidebar-list-depth-1", "sidebar-list-depth-2", + "sidebar-list-depth-3", "sidebar-mobile-overlay", "sidebar-mobile-panel", "sidebar-nav", @@ -521,6 +516,7 @@ "split-card", "split-card-eyebrow", "subheading-anchor", + "table-capped", "table-wrapper", "terminal", "terminal-badges", @@ -538,21 +534,18 @@ ], "ids": [ "about-prompts", - "about-publishing-agents", - "about-publishing-mcp-servers", - "about-publishing-skills", - "about-this-guide", + "about-skills", + "about-the-registry-catalog", "access-the-ui", "add-a-prompt-to-an-agent", "add-a-skill", + "add-a-tool", "add-mcp-server", - "add-tools", "agents", "ar-orbit", "arctl-cli", "artifact-registry-infrastructure", "artifacts", - "available-tools", "backToTop", "bash", "bb-panel", @@ -561,7 +554,7 @@ "bb-panel-title", "before-you-begin", "build-package-and-deploy", - "build-the-skill-optional", + "build-the-image", "catalog", "catalog-preview", "centralized-governance-and-curation", @@ -569,7 +562,6 @@ "cleanup", "command-specific-flags", "component-architecture", - "configure-a-client", "connect-to-the-mcp-server", "content", "create-a-prompt", @@ -583,16 +575,12 @@ "db-migrate-up", "db-migrate-version", "deploy", - "deploy-the-agent", "deploy-the-mcp-server", "deployed-view", "disclosures", "discovery", "discovery-across-environments", - "docker", - "docker-local", "evaluation", - "example", "explore-the-ui", "faqs", "favicon-svg", @@ -603,8 +591,7 @@ "get-started", "global-flags", "how-agentregistry-fills-the-gaps", - "how-it-works", - "install", + "install-agentregistry", "install-the-arctl-cli", "install-with-helm", "kubernetes", @@ -615,22 +602,19 @@ "mobile-icons-toggle", "next", "next-steps", - "option-1-publish-with-a-docker-image-from-local-folder", - "option-2-publish-from-a-github-repository-with-local-folder", - "option-3-direct-registration-with-github-no-local-files-needed", - "option-4-direct-registration-with-docker-image-no-local-files-needed", "plugins", "postgresql", "powershell", "preview-appbar", "prompts", "public-disclosure", - "publish-the-agent-image", + "publish-the-agent", "publish-the-prompt", "publish-the-server", "publish-the-skill", - "pull-a-skill", + "pull-a-skill-from-the-registry", "quickstart", + "register-the-remote-mcp-server", "registry-server", "registry-ui", "remediation", @@ -640,41 +624,45 @@ "run-the-mcp-server", "runtimes", "servers", - "setup", "skills", "skills-and-prompt-version-drift", "solo-back-to-top", - "specify-a-version", "step-1-create-the-agentregistry-database", + "step-1-install-kagent", "step-2-configure-agentregistry", + "step-2-verify-the-runtime", + "step-2-verify-the-runtime-connection", "sub-commands", "supported-clients", "supported-tools", "tabs-panel-tabs-00-0", "tabs-panel-tabs-00-1", + "tabs-panel-tabs-01-0", + "tabs-panel-tabs-01-1", "tabs-panel-tabs-02-0", "tabs-panel-tabs-02-1", "tabs-panel-tabs-03-0", "tabs-panel-tabs-03-1", - "tabs-panel-tabs-08-0", - "tabs-panel-tabs-08-1", + "tabs-panel-tabs-04-0", + "tabs-panel-tabs-04-1", "tabs-tab-tabs-00-0", "tabs-tab-tabs-00-1", + "tabs-tab-tabs-01-0", + "tabs-tab-tabs-01-1", "tabs-tab-tabs-02-0", "tabs-tab-tabs-02-1", "tabs-tab-tabs-03-0", "tabs-tab-tabs-03-1", - "tabs-tab-tabs-08-0", - "tabs-tab-tabs-08-1", + "tabs-tab-tabs-04-0", + "tabs-tab-tabs-04-1", "terminal", "terminal-body", - "the-skillmd-file", + "test-the-deployed-server", "theme-toggle", "tribal-knowledge-and-informal-sharing", "updates-and-questions", "usage", - "verify-the-connection", - "verify-the-published-skill", + "verify-the-deployment", "zsh" ] } From 1551d550188c6d119fa9639c465d034be3314a76 Mon Sep 17 00:00:00 2001 From: Nadine2016 Date: Thu, 20 Aug 2026 09:40:36 -0400 Subject: [PATCH 4/4] Review comments Signed-off-by: Nadine2016 --- content/docs/about/about.md | 2 +- content/docs/about/architecture.md | 2 +- content/docs/mcp/local/create.md | 6 +++--- content/docs/mcp/local/publish.md | 22 +++++++++++++--------- content/docs/mcp/remote.md | 2 +- content/docs/operations/database.md | 2 +- content/docs/skills/publish.md | 10 +++++----- hugo_stats.json | 9 --------- 8 files changed, 25 insertions(+), 30 deletions(-) diff --git a/content/docs/about/about.md b/content/docs/about/about.md index 34fb6f0..5fe652f 100644 --- a/content/docs/about/about.md +++ b/content/docs/about/about.md @@ -1,7 +1,7 @@ --- title: What is agentregistry? weight: 10 -description: "Learn more about agentregisty." +description: Learn more about agentregistry. --- Agentregistry is an open source, centralized AI artifact catalog that helps you build, package, publish, and discover AI artifacts, including agents, skills, MCP servers, prompts, and plugins that are spread across multiple container registries and GitHub repositories. It provides a single source of truth for the AI building blocks your teams are allowed to share, deploy, and compose into applications. diff --git a/content/docs/about/architecture.md b/content/docs/about/architecture.md index 6a39f15..d887611 100644 --- a/content/docs/about/architecture.md +++ b/content/docs/about/architecture.md @@ -14,7 +14,7 @@ The following diagram shows the components that make up agentregistry and how th ### Registry server -The registry server is the core of the control plane that manages the artifact catalog, deployments, and runtime connections. It serves the registry UI and the REST API that is used by the `arctl` CLI and other integrations. The server listens on port `12121` by default and exposes the registry as an MCP server on port `13131`. +The registry server is the core of the control plane that manages the artifact catalog, deployments, and runtime connections. It serves the registry UI and the REST API that is used by the `arctl` CLI and other integrations. The server listens on port `12121` by default and exposes the registry as an MCP server on port `31313`. ### PostgreSQL diff --git a/content/docs/mcp/local/create.md b/content/docs/mcp/local/create.md index 2509edb..da2c556 100644 --- a/content/docs/mcp/local/create.md +++ b/content/docs/mcp/local/create.md @@ -25,9 +25,9 @@ Agentregistry comes with built-in MCP server templates that you can use to quick 🚀 Next steps: 1. Run locally (optional): - arctl run my-mcp + arctl run mymcp 2. Publish to the registry: - arctl apply -f my-mcp/mcp.yaml + arctl apply -f mymcp/mcp.yaml ``` 2. Explore the MCP server scaffold. You can make changes to the files to customize your server. @@ -76,7 +76,7 @@ Agentregistry comes with built-in MCP server templates that you can use to quick 3. Try out an MCP tool. 1. Navigate to the **Tools** tab. Verify that you see the `example_echo` and `example_sum` tools. - 2. Select the `example_sum` tool and enter any two integer in the **a** and **b** fields. + 2. Select the `example_sum` tool and enter any two integers in the **a** and **b** fields. 3. Click **Execute Tool** and verify that you see the sum of the two integers. {{< reuse-image src="img/ar-mcp-sum.svg" srcDark="img/ar-mcp-sum-dark.svg" >}} diff --git a/content/docs/mcp/local/publish.md b/content/docs/mcp/local/publish.md index 3e8e309..95b21d5 100644 --- a/content/docs/mcp/local/publish.md +++ b/content/docs/mcp/local/publish.md @@ -33,18 +33,22 @@ Before you can add an MCP server to the catalog, you must build a Docker contain docker login ghcr.io ``` -3. Build the MCP server image from within the MCP project directory and push it to your registry. +3. Build the MCP server image and push it to your registry. {{< tabs >}} {{% tab name="Multi-arch (recommended)" %}} - Use the `docker buildx` command to build a multi-architecture image. - - ```sh - docker buildx build --platform linux/amd64,linux/arm64 \ - --label io.modelcontextprotocol.server.name="mymcp" \ - --tag $REGISTRY/mymcp:latest \ - --push . - ``` + 1. Navigate into your MCP project directory. + ```sh + cd mymcp + ``` + 2. From within the project directory, use the `docker buildx` command to build a multi-architecture image. + + ```sh + docker buildx build --platform linux/amd64,linux/arm64 \ + --label io.modelcontextprotocol.server.name="mymcp" \ + --tag $REGISTRY/mymcp:latest \ + --push . + ``` {{% /tab %}} {{% tab name="Single-arch" %}} diff --git a/content/docs/mcp/remote.md b/content/docs/mcp/remote.md index a8edf87..ff8f054 100644 --- a/content/docs/mcp/remote.md +++ b/content/docs/mcp/remote.md @@ -17,7 +17,7 @@ The following example registers the [GitHub MCP server](https://github.com/githu 1. Save your GitHub Personal Access Token in an environment variable. ```sh - export GH_PATH= + export GH_PAT= ``` 2. Create a registry catalog entry for your remote MCP server. diff --git a/content/docs/operations/database.md b/content/docs/operations/database.md index 2856d8d..22822c2 100644 --- a/content/docs/operations/database.md +++ b/content/docs/operations/database.md @@ -10,7 +10,7 @@ For production environments, replace the bundled database with an external Postg ## Before you begin -1. Creata or use an existing external PostgreSQL instance (version 14 or later) that is reachable from your agentregistry installation. For example, you can create an [Amazon RDS instance](https://aws.amazon.com/rds/resources/) +1. Create or use an existing external PostgreSQL instance (version 14 or later) that is reachable from your agentregistry installation. For example, you can create an [Amazon RDS instance](https://aws.amazon.com/rds/resources/) 2. Install agentregistry on [Kubernetes]({{< link path="/setup/kubernetes" >}}). ## Step 1: Create the agentregistry database diff --git a/content/docs/skills/publish.md b/content/docs/skills/publish.md index 5d0e27a..adcc2f5 100644 --- a/content/docs/skills/publish.md +++ b/content/docs/skills/publish.md @@ -56,7 +56,7 @@ Agentregistry comes with a built-in skill template that you can use to quickly s | `scripts/` | Directory for helper scripts, such as the starter `hello_world.py` example. | | `LICENSE.txt` | License information for the skill. | -3. Review the skill definition. This file describes that catalog entry that you want to create in the registry. Note that the scaffold does not include the reference to your git repository by default. You later update this skill definition to add your git reference. +3. Review the skill definition. This file describes that catalog entry that you want to create in the registry. ```sh cat myskill/skill.yaml ``` @@ -69,7 +69,7 @@ Agentregistry comes with a built-in skill template that you can use to quickly s name: myskill spec: description: myskill skill - title: myskill + title: myskill ``` 4. Review and optionally edit the `myskill/SKILL.md` file to define your skill's instructions. Use the frontmatter to set the catalog metadata, such as the name and description for the catalog entry in the UI, and the markdown body to define your skill. @@ -134,8 +134,8 @@ Before you publish the skill in the registry catalog, it is recommended to store ```console ✓ Skill/myskill (latest) created ``` - - The skill controller resolves the branch to a concrete commit and records it in the `status.resolvedSource.commit` of your skill, so the registry always tracks exactly which revision is live. + 2. Verify that the skill was registered. @@ -146,7 +146,7 @@ Before you publish the skill in the registry catalog, it is recommended to store Example output: ```console NAME TAG DESCRIPTION - myskill latest A reusable skill stored in git. + myskill latest myskill skill ``` 3. Optional: Open the [agentregistry UI](http://localhost:12121) and go to the **Skills** view. Verify that you can see your skill. diff --git a/hugo_stats.json b/hugo_stats.json index c93a668..0cf9f2b 100644 --- a/hugo_stats.json +++ b/hugo_stats.json @@ -631,30 +631,21 @@ "step-1-install-kagent", "step-2-configure-agentregistry", "step-2-verify-the-runtime", - "step-2-verify-the-runtime-connection", "sub-commands", "supported-clients", "supported-tools", - "tabs-panel-tabs-00-0", - "tabs-panel-tabs-00-1", "tabs-panel-tabs-01-0", "tabs-panel-tabs-01-1", "tabs-panel-tabs-02-0", "tabs-panel-tabs-02-1", "tabs-panel-tabs-03-0", "tabs-panel-tabs-03-1", - "tabs-panel-tabs-04-0", - "tabs-panel-tabs-04-1", - "tabs-tab-tabs-00-0", - "tabs-tab-tabs-00-1", "tabs-tab-tabs-01-0", "tabs-tab-tabs-01-1", "tabs-tab-tabs-02-0", "tabs-tab-tabs-02-1", "tabs-tab-tabs-03-0", "tabs-tab-tabs-03-1", - "tabs-tab-tabs-04-0", - "tabs-tab-tabs-04-1", "terminal", "terminal-body", "test-the-deployed-server",