Update agent section

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 >}}

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 <cluster-name>
+   kind load docker-image $REGISTRY/mymcp:latest --name <cluster-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- <<EOF
+   apiVersion: ar.dev/v1alpha1
+   kind: Deployment
+   metadata:
+     name: myagent
+   spec:
+     targetRef:
+       kind: Agent
+       name: myagent
+       tag: latest
+     runtimeRef:
+       kind: Runtime
+       name: kubernetes-default
+     env:
+       GOOGLE_API_KEY: ${GOOGLE_API_KEY}
+   EOF
+   ```
+
+   Example output:
+   ```console
+   ✓ Deployment/myagent configured
+   ```
+
+5. Verify that the deployment was created.
+   ```sh
+   arctl get deployments
+   ```
+
+6. Verify that the agent pod is running in your cluster. If you referenced an MCP server in your agent manifest, the MCP server is also deployed as a pod in to the cluster. 
+   ```sh
+   kubectl get pods -n agentregistry | grep myagent
+   ```
+
+   Example output:
+   ```console
+   myagent-latest-myagent-656bf798b-2dph6     1/1     Running   0          35m
+   mymcp-myagent-669c4bdf68-cvvv6             1/1     Running   0          35m
+   ``` 
+
+7. Optional: Verify the agent and, if applicable, the MCPServer resources that were deployed to your cluster.
+   ```sh
+   kubectl get agent -A -o yaml
+   kubectl get mcpserver -A -o yaml
+   ```
+
+   > [!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
+   ```