diff --git a/assets/img/kagent-agent-chat-dark.svg b/assets/img/kagent-agent-chat-dark.svg new file mode 100644 index 0000000..da935e9 --- /dev/null +++ b/assets/img/kagent-agent-chat-dark.svg @@ -0,0 +1,4 @@ + + + \ No newline at end of file diff --git a/assets/img/kagent-agent-chat.svg b/assets/img/kagent-agent-chat.svg new file mode 100644 index 0000000..a4fdbce --- /dev/null +++ b/assets/img/kagent-agent-chat.svg @@ -0,0 +1,4 @@ + + + \ No newline at end of file diff --git a/assets/img/kagent-agent-mcp-chat-dark.svg b/assets/img/kagent-agent-mcp-chat-dark.svg new file mode 100644 index 0000000..65fe485 --- /dev/null +++ b/assets/img/kagent-agent-mcp-chat-dark.svg @@ -0,0 +1,4 @@ + + + \ No newline at end of file diff --git a/assets/img/kagent-agent-mcp-chat.svg b/assets/img/kagent-agent-mcp-chat.svg new file mode 100644 index 0000000..f12180c --- /dev/null +++ b/assets/img/kagent-agent-mcp-chat.svg @@ -0,0 +1,4 @@ + + + \ No newline at end of file diff --git a/content/docs/agents/create.md b/content/docs/agents/create.md index 45f794f..103c2a8 100644 --- a/content/docs/agents/create.md +++ b/content/docs/agents/create.md @@ -11,9 +11,11 @@ description: "Scaffold an agent and run it locally by using agentregistry." ## Create an agent +In this guide, you create a Python agent by using the [Google Agent Development Kit (ADK)](https://google.github.io/adk-docs/) framework. ADK is an open-source framework for building AI agents. The agent uses Gemini as its language model, which requires a Google API key to authenticate requests to the Gemini API. + 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 scaffolds a `myagent` Python agent with the ADK framework, configured to use the `gemini-2.5-flash` model. 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 tools to roll a die and check whether a number is prime. ```sh arctl init agent myagent --framework adk --language python --model-provider gemini --model-name gemini-2.5-flash @@ -53,7 +55,26 @@ description: "Scaffold an agent and run it locally by using agentregistry." | `pyproject.toml` | Python project dependencies. | | `README.md` | Introduction and customization instructions for the scaffolded agent. | -## Run the agent +3. Review the agent manifest that was created for you. Note that by default, agentregistry adds a default image source of `ghcr.io/myagent:latest` to the manifest. This image location is later used when you build the agent image or push it to your container registry. To learn how to update this image reference, see the [Publish to catalog]({{< link path="/agents/publish/" >}}) guide. + ```sh + cat myagent/agent.yaml + ``` + + Example output: + ```console + apiVersion: ar.dev/v1alpha1 + kind: Agent + metadata: + name: myagent + spec: + description: myagent agent + source: + image: ghcr.io/myagent:latest + ``` + +## Run the agent locally + +You can try out the agent that the scaffold created by using the `arctl run` command. The agent uses Gemini as its language model, so you need a Google API key to authenticate requests to the Gemini API. 1. Set your Gemini API key. You can retrieve it from the [Google AI Studio](https://aistudio.google.com/app/api-keys). @@ -78,5 +99,6 @@ description: "Scaffold an agent and run it locally by using agentregistry." ## Next {{< cards >}} +{{< card link="../mcp/" title="Add MCP servers" description="Give your agent access to tools exposed by an MCP server." >}} {{< 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/kagent.md b/content/docs/agents/deploy/kagent.md new file mode 100644 index 0000000..b68fb5d --- /dev/null +++ b/content/docs/agents/deploy/kagent.md @@ -0,0 +1,124 @@ +--- +title: kagent +weight: 20 +description: "Deploy an agent in your Kubernetes cluster." +--- + +## Before you begin + +1. Follow the [Get started](/docs/quickstart/) guide to install agentregistry. +2. [Connect the kagent runtime]({{< link path="/setup/runtime/" >}}) so that you can deploy agents to your Kubernetes cluster. +3. [Publish an agent](/docs/agents/publish/). + + +## Deploy the agent {#deploy} + +1. List the runtimes that are connected to agentregistry. Make sure that you see the `kubernetes-default` runtime. This runtime leverages kagent to deploy agents and MCP servers to your Kubernetes cluster. + ```sh + arctl get runtimes + ``` + + Example output: + ```console + NAME TYPE + kubernetes-default kubernetes + ``` + +2. List the agents that are published in agentregistry. Note the name and tag of the agent you want to deploy. + ```sh + arctl get agents + ``` + + Example output: + ```console + NAME TAG MODE DESCRIPTION + myagent latest source My agent + ``` + +3. If you are using a local [kind](https://kind.sigs.k8s.io/) cluster, load the agent image that you previously built, and the images of any referenced MCP servers, into the cluster. Skip this step if you are using a remote registry that your cluster can pull from directly. + ```sh + kind load docker-image $REGISTRY/myagent:latest --name + kind load docker-image $REGISTRY/mymcp:latest --name + ``` + +4. Create a Deployment that references your agent and the `kubernetes-default` runtime. The `env` field passes environment variables to the agent container at runtime. If your agent uses Gemini as its language model, it requires a `GOOGLE_API_KEY` to authenticate requests to the Gemini API. + + ```yaml + arctl apply -f- < [!NOTE] + > If the deployment fails, you can view it with `arctl get deployments`. Remove the failed deployment with `arctl delete deployment myagent` and re-apply after fixing the issue. + + +## Verify the agent + +1. Open the kagent dashboard. + ```sh + kagent dashboard + ``` + +2. Navigate to your agent and start chatting with the agent. For example, you can ask it what it can do for you. Verify that the agent replies that it can roll a die and check if numbers are prime. + ```sh + what can you do for me + ``` + {{< reuse-image src="img/kagent-agent-chat.svg" srcDark="img/kagent-agent-chat-dark.svg" >}} + + If you also referenced an MCP server, make sure that the agent also lists the MCP server tools it has access to. + + {{< reuse-image src="img/kagent-agent-mcp-chat.svg" srcDark="img/kagent-agent-mcp-chat-dark.svg" >}} + +## Cleanup + + +1. List deployments and find the one to remove. + ```sh + arctl get deployments + ``` + +2. Delete the deployment. + ```sh + arctl delete deployment myagent + ``` diff --git a/content/docs/agents/deploy/kubernetes.md b/content/docs/agents/deploy/kubernetes.md deleted file mode 100644 index dd4c22e..0000000 --- a/content/docs/agents/deploy/kubernetes.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Kubernetes -weight: 20 -description: "Deploy an agent in your Kubernetes cluster." ---- - -Deploy your agent to a Kubernetes cluster. - -## Before you begin - -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} - -1. Deploy the agent to your cluster. - ```sh - arctl deployments create myagent \ - --type agent \ - --provider-id kubernetes-default \ - --namespace default - ``` - - Example output: - ```console - Waiting for agent 'myagent' to become ready... - Agent 'myagent' version 'latest' deployed to providerId=kubernetes-default in namespace 'default' - ``` - - > [!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 agent is up and running. - ```sh - kubectl get pods | grep myagent - ``` - - Example output: - ```console - NAME READY STATUS RESTARTS AGE - myagent-latest-687c4c88b9-xwjzx 1/1 Running 0 10s - ``` - -3. Optional: Verify the Agent and, if applicable, the MCPServer resources that were deployed to your cluster. - ```sh - kubectl get agent -o yaml - 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/agents/mcp.md b/content/docs/agents/mcp.md index d4e3b8b..db6bda3 100644 --- a/content/docs/agents/mcp.md +++ b/content/docs/agents/mcp.md @@ -1,11 +1,9 @@ --- title: Add MCP servers -description: "Give an agent access to the tools exposed by an MCP server." -weight: 50 +description: Give an agent access to the tools that are exposed by an MCP server. +weight: 20 --- -Give an agent access to the tools that are exposed on an MCP server. - ## Before you begin 1. Follow the [Get started](/docs/quickstart/) guide to set up agentregistry and start the agentregistry daemon. @@ -13,91 +11,53 @@ Give an agent access to the tools that are exposed on an MCP server. 3. [Create an MCP server](/docs/mcp/local/create/). 4. [Publish an MCP server](/docs/mcp/local/publish/). -## Add MCP server - -1. List the MCP servers that are published in agentregistry. - ```sh - arctl mcp list - ``` - - Example output: - ``` - NAME VERSION TYPE PUBLISHED DEPLOYED UPDATED - user/my-mcp-server 0.1.0 oci True False 7s - ``` - -2. Add the MCP server to the `myagent` agent that you created as part of the before you begin steps. This command opens an interactive dialog in your terminal. - ```sh - arctl agent add-mcp --project-dir myagent - ``` - -3. Go through the interactive dialog. - 1. Use the arrow keys to go to `3. Registry (pull published MCP server from registry)`. This option allows you to select an MCP server that you previously published to the registry. Press the return key to continue. - 2. Enter `http://localhost:12121` as the registry URL and press the return key. - 3. Select the MCP server that you published to agentregistry and the version you want to use. - 4. Select `true` in the `Prefer remote MCP server` dialog. - 5. Enter the following environment variables. By default, the MCP server scaffolding assumes that you want to run the MCP server with `stdio`. However, streamable HTTP is required to successfully connect to the MCP server from the agent. - | Key | Value | - | -- | -- | - | `MCP_TRANSPORT_MODE` | `http` | - | `HOST` | `0.0.0.0` | - 6. Enter `my-mcp-server` as the MCP server name and press the return key to exit the wizard. +## Add an MCP server to the agent - Example output: - ```sh - ✓ Added MCP server 'my-mcp-server' (registry) to agent.yaml - ``` +MCP servers are referenced in the agent manifest in the `spec.mcpServers` block. Each MCP server that you reference in that block must be published in the registry catalog. -4. Verify that your MCP server tool reference is added to the agent by reviewing the agent definition in the `agent.yaml` file. +1. List the MCP servers that are published in the registry catalog. ```sh - cat myagent/agent.yaml + arctl get mcps ``` - Example output: + Example output: ```console - agentName: myagent - image: ghcr.io/myagent:latest - language: python - framework: adk - modelProvider: gemini - modelName: gemini-2.0-flash - description: "" - mcpServers: - - type: registry - name: my-mcp-server - env: - - MCP_TRANSPORT_MODE=http - - HOST=0.0.0.0 - registryURL: http://localhost:12121 - registryServerName: user/my-mcp-server - registryServerVersion: 0.1.0 - registryServerPreferRemote: true + NAME TAG DESCRIPTION + mymcp latest mymcp MCP server ``` -5. Build the agent image. - ```sh - arctl agent build myagent - ``` +2. Add an `mcpServers` block to your agent definition (`agent.yaml`) and reference the MCP server that you want your agent to have access to. -6. Run the agent. Wait for the agent dialog to open. - ```sh - arctl agent run myagent + ```yaml + cat > myagent/agent.yaml <}} - {{< reuse-image-dark srcDark="img/ar-agent-tool.png" >}} - -8. Try out the echo tool by entering `echo `, such as `echo hello world`. Verify that you see the MCP tool call and that the agent returns `hello world`. - {{< reuse-image src="img/ar-agent-tool-verify.png" >}} - {{< reuse-image-dark srcDark="img/ar-agent-tool-verify.png" >}} + | Field | Description | + | -- | -- | + | `mcpServers[].kind` | Must be `MCPServer`. | + | `mcpServers[].name` | Name of the MCP server in agentregistry. | + | `mcpServers[].tag` | Tag to use. If omitted, the latest tag is resolved at deploy time. | -## Next +> [!NOTE] +> MCP servers are referenced in the agent manifest and resolved from the registry at deploy time. You cannot locally test access to the MCP server tools by using the `arctl run agent` command. To test access to the tools, you must publish the agent in the registry catalog and deploy the agent to your runtime. -[Deploy the agent to your environment](/docs/agents/deploy/). -## Cleanup - -To remove the MCP server tool, edit the `agent.yaml` definition and remove the MCP server reference. Then, re-build the agent and run it. +## Next +{{< 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/prompt.md b/content/docs/agents/prompt.md deleted file mode 100644 index 4756017..0000000 --- a/content/docs/agents/prompt.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Add prompt -weight: 60 -description: Add a published prompt to an agent so that it is used as the agent's instruction at runtime. ---- - - -## 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/), such as with the `arctl agent init` command. -3. [Publish a prompt in agentregistry](/docs/prompts/publish/). - - -## Add a prompt to an agent - -1. List the prompts that are published in agentregistry. - ```sh - arctl prompt list - ``` - - Example output: - ```console - NAME VERSION DESCRIPTION - code-review 1.0.0 System prompt for code review agent - ``` - -2. Add a prompt reference to the agent manifest (`agent.yaml`). The `--registry-prompt-name` flag specifies the prompt name that you used when you published the skill in agentregistry. The following command adds a `prompts` section to your `agent.yaml` file. You can pin a specific version by using the `--registry-prompt-version` flag. If omitted, the latest version is resolved at runtime. - - ```sh - arctl agent add-prompt reviewer \ - --project-dir myagent \ - --registry-prompt-name code-review - ``` - - > [!TIP] - > To use a prompt from a different registry, use the `--registry-url` flag. - > ```sh - > arctl agent add-prompt reviewer \ - > --registry-prompt-name code-review \ - > --registry-url https://registry.example.com - > ``` - - Example output: - ```console - ✓ Added prompt 'reviewer' to agent.yaml - ``` - -3. After adding a prompt, verify that the `agent.yaml` file was updated. - ```sh - cat myagent/agent.yaml - ``` - - Example `prompts` section in the `agent.yaml` file: - - ```console - prompts: - - name: reviewer - registryURL: http://localhost:12121 - registryPromptName: code-review - registryPromptVersion: latest - ``` - -4. Re-build the agent image. - ```sh - arctl agent build myagent - ``` - -5. Run the agent. When you run the agent with `arctl agent run`, the following steps are execute: - - 1. The CLI reads the `prompts` section from the `agent.yaml` file. - 2. For each prompt reference, the CLI fetches the prompt content from the registry's REST API. - 3. The resolved prompt content is written to a `prompts.json` file in the agent's config directory. - 4. The agent's `prompts_loader.py` (autogenerated) reads the `prompts.json` file at startup. - 5. The `build_instruction()` function returns the resolved prompt content as the agent's instruction, replacing the default instruction. - - ```sh - arctl agent run myagent - ``` - - > [!TIP] - > If no prompts are resolved (for example, the registry is unreachable or no prompts are configured), the agent falls back to the default instruction defined in the `agent.py` file. - -6. Ask the agent what it checks during a code review. Verify that you get back the steps that you defined in your prompt. - - {{< reuse-image src="img/ar-agent-prompt-verify.png" >}} - {{< reuse-image-dark srcDark="img/ar-agent-prompt-verify.png" >}} - - -## Next - -[Deploy the agent to your environment](/docs/agents/deploy/). - - -## Cleanup - -To remove a prompt from the agent, edit the `agent.yaml` file and remove the prompt reference from the `prompts` list. Then, re-build and re-run or re-deploy the agent. - - diff --git a/content/docs/agents/prompt.txt b/content/docs/agents/prompt.txt new file mode 100644 index 0000000..948fd8d --- /dev/null +++ b/content/docs/agents/prompt.txt @@ -0,0 +1,85 @@ +--- +title: Add prompt +weight: 60 +description: Add a published prompt to an agent so that it is used as the agent's instruction at runtime. +--- + +## 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/). +3. [Publish a prompt in agentregistry](/docs/prompts/publish/). + +## Add a prompt to an agent + +Prompts are referenced in the agent manifest under `spec.instructions`. Because a prebuilt image cannot consume injected content on its own, agents that use `instructions` must also declare which harnesses they are compatible with via `spec.compatibleHarnesses`. + +1. List the prompts published in agentregistry. + ```sh + arctl get prompts + ``` + + Example output: + ```console + NAME TAG DESCRIPTION + summarizer-system-prompt stable Default system prompt for summarization agents + ``` + +2. Add an `instructions` reference and a `compatibleHarnesses` entry to your agent manifest. + + ```yaml + apiVersion: ar.dev/v1alpha1 + kind: Agent + metadata: + name: my-agent + spec: + source: + image: ghcr.io/myorg/my-agent:v1.0.0 + description: "My agent" + compatibleHarnesses: + - type: claude-code + instructions: + kind: Prompt + name: summarizer-system-prompt + tag: stable + ``` + + | Field | Description | + | -- | -- | + | `instructions.kind` | Must be `Prompt`. | + | `instructions.name` | Name of the prompt in agentregistry. | + | `instructions.tag` | Tag to use. If omitted, the latest tag is resolved at deploy time. | + | `compatibleHarnesses[].type` | Harness family this agent can run under, for example `claude-code` or `codex`. Required when `instructions` is set. | + +3. Apply the updated agent manifest. + ```sh + arctl apply -f agent.yaml + ``` + + Example output: + ```console + agent/my-agent applied + ``` + +4. Verify that the agent was updated. + ```sh + arctl get agent my-agent + ``` + +## Next + +[Deploy the agent to your environment](/docs/agents/deploy/). + +## Cleanup + +To remove the prompt from the agent, delete the `instructions` field from the agent manifest and apply the updated file. + +```sh +arctl apply -f agent.yaml +``` + +To delete the prompt resource from agentregistry, run: + +```sh +arctl delete prompt summarizer-system-prompt +``` diff --git a/content/docs/agents/publish.md b/content/docs/agents/publish.md index d451901..d22cba8 100644 --- a/content/docs/agents/publish.md +++ b/content/docs/agents/publish.md @@ -1,5 +1,5 @@ --- -title: Publish +title: Publish to catalog weight: 20 description: "Add your agent to the registry catalog." --- @@ -10,11 +10,58 @@ Build your agent image and publish it to agentregistry so your team can discover 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. Make sure you are logged in to your container registry. -## Publish the agent +## Build the agent image + +1. Set your container registry URL, such as `ghcr.io/myorg`. This value is used to construct the image reference in your agent manifest. + + ```sh + export REGISTRY= + ``` + +2. Update the agent manifest with your registry URL. Select the tab that matches your setup. + + {{< tabs >}} + {{% tab name="Agent-only" %}} + + ```yaml + cat > myagent/agent.yaml < myagent/agent.yaml <}} +3. Build the Docker image for your agent by using the image source information from your agent manifest. You can optionally use the `--push` flag to also push the image to your container registry. ```sh arctl build myagent ``` @@ -23,13 +70,17 @@ Build your agent image and publish it to agentregistry so your team can discover ```console [+] Building 48.4s (12/12) FINISHED ... - ✅ Successfully built Docker image: ghcr.io/myagent:latest + ✅ Successfully built Docker image: ghcr.io/myorg/myagent:latest ``` > [!TIP] - > 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. + > To build a multi-architecture image (for example, to support both `amd64` and `arm64` nodes in your cluster), add `--platform linux/amd64,linux/arm64`. For more information, see the [arctl build](/docs/reference/cli/arctl-build/) command. + +## Publish the agent + +Create a catalog entry for your agent. -2. Publish the agent to agentregistry. The following command registers your `agent.yaml` definition in the catalog. +1. Publish the agent manifest to agentregistry. ```sh arctl apply -f myagent/agent.yaml @@ -37,10 +88,10 @@ Build your agent image and publish it to agentregistry so your team can discover Example output: ```console - agent.agentregistry.dev/myagent applied + ✓ Agent/myagent created ``` -3. List the agents in agentregistry. Verify that you see an entry for `myagent`. +2. Verify that the agent was published. ```sh arctl get agents @@ -48,17 +99,18 @@ Build your agent image and publish it to agentregistry so your team can discover Example output: ```console - NAME FRAMEWORK LANGUAGE PROVIDER MODEL DEPLOYED PUBLISHED - myagent adk python gemini gemini-2.0-flash False True + NAME TAG DESCRIPTION + myagent latest myagent agent ``` -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" >}} +3. Open the [agentregistry UI](http://localhost:12121) and go to the **Agents** view to review your published agent. + {{< reuse-image src="img/ar-list-agent.png" srcDark="img/ar-list-agent-dark.png" >}} ## Next -Now that you published the agent, you can [deploy the agent to your environment](/docs/agents/deploy/). +{{< cards >}} +{{< card link="../deploy/" title="Deploy the agent" description="Deploy your agent to your environment." >}} +{{< /cards >}} ## Cleanup diff --git a/content/docs/agents/skills.md b/content/docs/agents/skills.md deleted file mode 100644 index 2f39dca..0000000 --- a/content/docs/agents/skills.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: Add skills -description: "Give an agent access to skills that are published in the registry catalog." -weight: 55 ---- - -Give an agent access to skills that are published in agentregistry. Skills are loaded into the agent at runtime and made available under the `/skills` folder. - -## 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/). -3. [Create and publish a skill](/docs/skills/publish/) to agentregistry. - -## Add a skill - -You can add a skill to your agent from two sources: a published skill in agentregistry, or a container image directly. - -### From the registry - -Add a skill that was previously published to agentregistry by referencing the skill name in the registry. - -1. List the skills that are published in agentregistry. - ```sh - arctl skill list - ``` - - Example output: - ``` - NAME TITLE VERSION TYPE SOURCE - hello-world-template 1.0.0 docker docker.io/user/hello-world-template:v1.0.0 - ``` - -2. Add the skill to your agent. - ```sh - arctl agent add-skill my-skill \ - --project-dir myagent \ - --registry-skill-name hello-world-template \ - --registry-skill-version 1.0.0 \ - --image - ``` - - > [!TIP] - > If the skill is packaged as a Docker image, you can reference it directly without publishing to the registry first. - > ```sh - > arctl agent add-skill my-skill \ - > --project-dir myagent \ - > --image docker.io/user/hello-world-template:v1.0.0 - > ``` - - Example output: - ``` - ✓ Added skill 'my-skill' to agent.yaml - ``` - - You can optionally specify a version and a registry URL: - - | Flag | Description | - | -- | -- | - | `--registry-skill-name` | Name of the skill in the registry. Required. | - | `--registry-skill-version` | Version to use. If omitted, the latest version is used. | - | `--registry-url` | Registry URL. If omitted, the default registry is used. | - -3. After adding a skill, verify that the `agent.yaml` file was updated. - ```sh - cat myagent/agent.yaml - ``` - - Example output: - ```console - agentName: myagent - image: ghcr.io/myagent:latest - language: python - framework: adk - modelProvider: gemini - modelName: gemini-2.0-flash - description: "" - skills: - - name: my-skill - registryURL: http://localhost:12121 - registrySkillName: hello-world-template - ``` - -4. Re-build the agent image. - ```sh - arctl agent build myagent - ``` - -5. Run the agent. When you run an agent locally, agentregistry resolves the skills from the registry and makes them available to the agent. Wait for the agent dialog to open. - - ```sh - arctl agent run myagent - ``` - - During startup, `arctl`: - - 1. Resolves each skill in the agent manifest from the registry. - 2. Downloads the skill contents. Docker-packaged skills are extracted from the container image. GitHub-hosted skills are cloned from the repository. - 3. Places all skill files in a temporary directory and sets the `KAGENT_SKILLS_FOLDER` environment variable to point to it. - 4. Mounts the skills directory into the agent container at `/skills` (read-only). The agent can then load and use the skills from the `/skills` folder at runtime. - -6. Ask the agent to describe what skills it has access to. Verify that you see the `hello-world-template` tool. - {{< reuse-image src="img/ar-agent-skill-verify.png" >}} - {{< reuse-image-dark srcDark="img/ar-agent-skill-verify.png" >}} - - -## Next - -[Deploy the agent to your environment](/docs/agents/deploy/). - - -## Cleanup - -To remove a skill from the agent, edit the `agent.yaml` file and remove the skill reference from the `skills` list. Then, re-build and re-run or re-deploy the agent. diff --git a/content/docs/agents/skills.txt b/content/docs/agents/skills.txt new file mode 100644 index 0000000..8ef405e --- /dev/null +++ b/content/docs/agents/skills.txt @@ -0,0 +1,87 @@ +--- +title: Add skills +description: "Give an agent access to skills that are published in the registry catalog." +weight: 55 +--- + +Give an agent access to skills published in agentregistry. Skills are referenced in the agent manifest and resolved from the registry at deploy time. + +## 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/). +3. [Create and publish a skill](/docs/skills/publish/) to agentregistry. + +## Add a skill + +Skills are referenced in the agent manifest under `spec.skills`. Because a prebuilt image cannot consume injected content on its own, agents that use `skills` must also declare which harnesses they are compatible with via `spec.compatibleHarnesses`. + +1. List the skills published in agentregistry. + ```sh + arctl get skills + ``` + + Example output: + ```console + NAME TAG DESCRIPTION + summarize stable Summarizes long text into concise form + ``` + +2. Add a `skills` reference and a `compatibleHarnesses` entry to your agent manifest. + + ```yaml + apiVersion: ar.dev/v1alpha1 + kind: Agent + metadata: + name: my-agent + spec: + source: + image: ghcr.io/myorg/my-agent:v1.0.0 + description: "My agent" + compatibleHarnesses: + - type: claude-code + skills: + - kind: Skill + name: summarize + tag: stable + ``` + + | Field | Description | + | -- | -- | + | `skills[].kind` | Must be `Skill`. | + | `skills[].name` | Name of the skill in agentregistry. | + | `skills[].tag` | Tag to use. If omitted, the latest tag is resolved at deploy time. | + | `compatibleHarnesses[].type` | Harness family this agent can run under, for example `claude-code` or `codex`. Required when `skills` is set. | + +3. Apply the updated agent manifest. + ```sh + arctl apply -f agent.yaml + ``` + + Example output: + ```console + agent/my-agent applied + ``` + +4. Verify that the agent was updated. + ```sh + arctl get agent my-agent + ``` + +## Next + +[Deploy the agent to your environment](/docs/agents/deploy/). + +## Cleanup + +To remove a skill from the agent, delete its entry from the `skills` list in the agent manifest and apply the updated file. + +```sh +arctl apply -f agent.yaml +``` + +To delete the skill resource from agentregistry, run: + +```sh +arctl delete skill summarize +``` diff --git a/content/docs/mcp/local/deploy/kagent.md b/content/docs/mcp/local/deploy/kagent.md index ec09fc0..212bee5 100644 --- a/content/docs/mcp/local/deploy/kagent.md +++ b/content/docs/mcp/local/deploy/kagent.md @@ -36,7 +36,7 @@ description: "Deploy your agentregistry MCP server to a Kubernetes cluster." apiVersion: ar.dev/v1alpha1 kind: Deployment metadata: - name: my-mcp-server + name: mymcp-server spec: env: KAGENT_NAMESPACE: default @@ -52,10 +52,10 @@ description: "Deploy your agentregistry MCP server to a Kubernetes cluster." Example output: ```console - ✓ Deployment/my-mcp-server created + ✓ Deployment/mymcp-server created ``` -3. List the deployments and verify that `my-mcp-server` appears. +3. List the deployments and verify that `mymcp-server` appears. ```sh arctl get deployments @@ -64,7 +64,7 @@ description: "Deploy your agentregistry MCP server to a Kubernetes cluster." Example output: ```console NAME TARGET VERSION TYPE RUNTIME STATUS - default/my-mcp-server mymcp latest mcp kubernetes-default deploying + default/mymcp-server mymcp latest mcp kubernetes-default deploying ``` ## Verify the deployment @@ -111,7 +111,7 @@ description: "Deploy your agentregistry MCP server to a Kubernetes cluster." 1. Port-forward the MCP server service. ```sh - kubectl port-forward service/mymcp-my-mcp-server 3000 + kubectl port-forward service/mymcp-mymcp-server 3000 ``` 2. In a separate terminal, list the available tools. Verify that you see the `example_echo` and `example_sum` tools. diff --git a/content/docs/mcp/local/publish.md b/content/docs/mcp/local/publish.md index 95b21d5..a19d867 100644 --- a/content/docs/mcp/local/publish.md +++ b/content/docs/mcp/local/publish.md @@ -35,25 +35,6 @@ Before you can add an MCP server to the catalog, you must build a Docker contain 3. Build the MCP server image and push it to your registry. - {{< tabs >}} - {{% tab name="Multi-arch (recommended)" %}} - 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" %}} - 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 ``` @@ -65,8 +46,8 @@ Before you can add an MCP server to the catalog, you must build a Docker contain ✓ Successfully built Docker image: ghcr.io/my-org/mymcp:latest ``` - {{% /tab %}} - {{< /tabs >}} + > [!TIP] + > To build a multi-architecture image (for example, to support both `amd64` and `arm64` nodes in your cluster), add `--platform linux/amd64,linux/arm64`. For more information, see the [arctl build](/docs/reference/cli/arctl-build/) command. ## Publish the server diff --git a/content/docs/setup/runtime.md b/content/docs/setup/runtime.md index b7d6f2a..b4fe105 100644 --- a/content/docs/setup/runtime.md +++ b/content/docs/setup/runtime.md @@ -43,7 +43,7 @@ The steps in this guide walk you through how to install the kagent open source p ## 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. +Agentregistry creates a `kubernetes-default` runtime during the installation. Confirm that it is listed. 1. List the runtimes in agentregistry. ```sh @@ -60,5 +60,5 @@ Agentregistry creates a `kubernetes-default` runtime during the installation. Co {{< 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." >}} +{{< card link="/docs/agents/deploy/kagent/" title="Deploy an agent" description="Deploy a published agent to your kagent runtime." >}} {{< /cards >}} diff --git a/content/docs/skills/publish.md b/content/docs/skills/publish.md index adcc2f5..4ba6e18 100644 --- a/content/docs/skills/publish.md +++ b/content/docs/skills/publish.md @@ -155,7 +155,6 @@ Before you publish the skill in the registry catalog, it is recommended to store ## Next steps {{< 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 >}} diff --git a/hugo_stats.json b/hugo_stats.json index 0cf9f2b..5408a94 100644 --- a/hugo_stats.json +++ b/hugo_stats.json @@ -4,6 +4,7 @@ "a", "article", "aside", + "blockquote", "body", "br", "button", @@ -540,6 +541,8 @@ "add-a-prompt-to-an-agent", "add-a-skill", "add-a-tool", + "add-an-mcp-server", + "add-an-mcp-server-to-the-agent", "add-mcp-server", "agents", "ar-orbit", @@ -554,6 +557,7 @@ "bb-panel-title", "before-you-begin", "build-package-and-deploy", + "build-the-agent-image", "build-the-image", "catalog", "catalog-preview", @@ -621,6 +625,7 @@ "reports", "rest-api", "run-the-agent", + "run-the-agent-locally", "run-the-mcp-server", "runtimes", "servers", @@ -634,12 +639,16 @@ "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-tab-tabs-00-0", + "tabs-tab-tabs-00-1", "tabs-tab-tabs-01-0", "tabs-tab-tabs-01-1", "tabs-tab-tabs-02-0", @@ -653,6 +662,7 @@ "tribal-knowledge-and-informal-sharing", "updates-and-questions", "usage", + "verify-the-agent", "verify-the-deployment", "zsh" ]