From 51e7b14216d17b91529c9e8c9e2fd13fa7c0c484 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Fri, 12 Dec 2025 11:58:42 -0500 Subject: [PATCH 1/5] Doc updates - for 0.7.5 - 0.7.7 releases Signed-off-by: Art Berger --- public/sitemap.xml | 213 +++++++++--------- src/app/docs/kagent/examples/a2a-byo/page.mdx | 54 +++++ .../docs/kagent/examples/crewai-byo/page.mdx | 8 + .../local-development/page.mdx | 48 +++- .../kagent/introduction/installation/page.mdx | 47 +++- .../operational-considerations/page.mdx | 137 +++++++++++ src/app/docs/kagent/operations/page.mdx | 1 + .../kagent/resources/cli/kagent-run/page.mdx | 19 ++ src/config/navigation.json | 5 + 9 files changed, 427 insertions(+), 105 deletions(-) create mode 100644 src/app/docs/kagent/operations/operational-considerations/page.mdx diff --git a/public/sitemap.xml b/public/sitemap.xml index 35d465c..85bb8a0 100644 --- a/public/sitemap.xml +++ b/public/sitemap.xml @@ -2,721 +2,728 @@ https://kagent.dev/agents - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/blog - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/community - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/concepts/agents - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/concepts/architecture - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/concepts - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/concepts/tools - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/examples/a2a-agents - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/examples/a2a-byo - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/examples/crewai-byo - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/examples/discord-a2a - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/examples/documentation - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/examples/langchain-byo - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/examples - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/examples/skills - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/examples/slack-a2a - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/getting-started/first-agent - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/getting-started/first-mcp-tool - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/getting-started/local-development - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/getting-started - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/getting-started/quickstart - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/getting-started/system-prompts - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/getting-started/tracing - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/introduction/installation - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/introduction - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/introduction/what-is-kagent - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/operations/debug - 2025-12-04 + 2025-12-12 + weekly + 0.8 + + + + https://kagent.dev/docs/kagent/operations/operational-considerations + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/operations - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/operations/uninstall - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/operations/upgrade - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/resources/api-ref - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-add-mcp - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-bug-report - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-build - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-completion - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-dashboard - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-deploy - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-get - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-help - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-init - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-install - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-invoke - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-mcp - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-run - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-uninstall - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-version - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/resources/faq - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/resources/helm - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/resources - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/resources/release-notes - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers/amazon-bedrock - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers/anthropic - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers/azure-openai - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers/byo-openai - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers/gemini - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers/google-vertexai - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers/ollama - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers/openai - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kmcp/deploy/install-controller - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kmcp/deploy - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kmcp/deploy/server - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kmcp/develop/fastmcp-python - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kmcp/develop/mcp-go - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kmcp/develop - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kmcp/introduction - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kmcp - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kmcp/quickstart - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kmcp/reference/api-ref - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kmcp/reference/kmcp-add-tool - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kmcp/reference/kmcp-build - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kmcp/reference/kmcp-completion - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kmcp/reference/kmcp-deploy - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kmcp/reference/kmcp-help - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kmcp/reference/kmcp-init - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kmcp/reference/kmcp-install - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kmcp/reference/kmcp-run - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kmcp/reference/kmcp-secrets - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kmcp/reference - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs/kmcp/secrets - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/docs - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/enterprise - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/page.tsx - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/tools - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/agents/argo-rollouts-conversion-agent - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/agents/cilium-crd-agent - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/agents/helm-agent - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/agents/istio-agent - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/agents/k8s-agent - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/agents/kgateway-agent - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/agents/observability-agent - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/agents/promql-agent - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/tools/istio - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/tools/kubernetes - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/tools/prometheus - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/tools/documentation - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/tools/helm - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/tools/argo - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/tools/grafana - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/tools/other - 2025-12-04 + 2025-12-12 weekly 0.8 https://kagent.dev/tools/cilium - 2025-12-04 + 2025-12-12 weekly 0.8 diff --git a/src/app/docs/kagent/examples/a2a-byo/page.mdx b/src/app/docs/kagent/examples/a2a-byo/page.mdx index 90e39a4..126f197 100644 --- a/src/app/docs/kagent/examples/a2a-byo/page.mdx +++ b/src/app/docs/kagent/examples/a2a-byo/page.mdx @@ -240,3 +240,57 @@ You can use the A2A host CLI to invoke the agent. This CLI is part of the [A2A s "taskId": "59d2b071-04e9-4fef-a0dd-e925dd13cceb" } ``` + +## More options + +Review more options that you might want to configure for your BYO ADK agents. + +### Lifespan hooks + +Lifespan hooks initialize or clean up tasks when your BYO agent starts up or shuts down. This feature is useful for tasks like connecting to external services, loading configuration, or cleaning up resources. + +To use lifespan hooks in your ADK agent, create a lifespan function and pass it to `KAgentApp`. + +1. Create a lifespan function in your agent code, such as the following python example. The lifespan function is an async context manager that runs in either startup and shutdown code. + + - **Startup code** (before `yield`): Executes when the agent container starts. + + - **Shutdown code** (after `yield`): Executes when the agent container stops. + + ```python + # basic/lifespan.py + import logging + from contextlib import asynccontextmanager + from typing import Any + + @asynccontextmanager + async def lifespan(app: Any): + # Startup: runs when the agent starts + logging.info("Lifespan: setup - initializing resources") + # Perform initialization tasks here + # For example: connect to databases, load configuration, etc. + + try: + yield # Agent is running + finally: + # Shutdown: runs when the agent stops + logging.info("Lifespan: teardown - cleaning up resources") + # Perform cleanup tasks here + # For example: close connections, save state, etc. + ``` + +2. Import and pass the lifespan to `KAgentApp`. + + ```python + # main.py or similar + from kagent.adk import KAgentApp + from basic import agent, lifespan # Import your agent and lifespan + + app = KAgentApp( + root_agent=agent.root_agent, + agent_card=agent.agent_card, + kagent_url=os.getenv("KAGENT_URL", "http://kagent-controller.kagent.svc.cluster.local:8083"), + app_name="basic_agent", + lifespan=lifespan.lifespan # Pass the lifespan function + ) + ``` diff --git a/src/app/docs/kagent/examples/crewai-byo/page.mdx b/src/app/docs/kagent/examples/crewai-byo/page.mdx index abba26b..4abc8d4 100644 --- a/src/app/docs/kagent/examples/crewai-byo/page.mdx +++ b/src/app/docs/kagent/examples/crewai-byo/page.mdx @@ -45,6 +45,14 @@ The following example builds a research crew agent from the [kagent code reposit A quickstart and detailed guide for adapting existing CrewAI crews and flows to work with kagent is available in the [package's README](https://github.com/kagent-dev/kagent/tree/main/python/packages/kagent-crewai). This provides a simple way to setup A2A server, tracing, and session-aware memory and state persistence. +The `kagent-crewai` package is published and available on PyPI. + +To install in your CrewAI project: + +```bash +pip install kagent-crewai +``` + Two complete examples are available in the `python/samples/crewai/` directory: - [**Crew Example**](https://github.com/kagent-dev/kagent/tree/main/python/samples/crewai/research-crew): A multi-agent crew for web research and analysis diff --git a/src/app/docs/kagent/getting-started/local-development/page.mdx b/src/app/docs/kagent/getting-started/local-development/page.mdx index 4987dd3..022bd5d 100644 --- a/src/app/docs/kagent/getting-started/local-development/page.mdx +++ b/src/app/docs/kagent/getting-started/local-development/page.mdx @@ -10,7 +10,7 @@ export const metadata = { author: "kagent.dev" }; -# Local developmeent with kagent CLI +# Local development with kagent CLI In this guide, you'll learn how to develop, build and run an AI agent locally using kagent CLI, without a Kubernetes cluster. This guide is meant for developers familiar with Python. You can also create declarative agents without writing a single line of code, by following the [Your First Agent](/docs/kagent/getting-started/first-agent) guide. @@ -263,6 +263,52 @@ mcpserver.kagent.dev/server-everything True 112s You can now test the deployed agent and the MCP server through kagent UI. +## Using PostgreSQL for local development + +By default, kagent uses SQLite for local development. For most local development, SQLite is sufficient and simpler to set up. However, you can also use PostgreSQL for local development, which is useful if you want to test with the same database backend that you use in production. + +The following steps show how to set up PostgreSQL with `docker-compose`. + +1. Add PostgreSQL service to your `docker-compose.yaml`. + + ```yaml + services: + postgres: + image: postgres:15-alpine + environment: + POSTGRES_USER: kagent + POSTGRES_PASSWORD: kagent + POSTGRES_DB: kagent + ports: + - "5432:5432" + volumes: + - postgres-data:/var/lib/postgresql/data + + volumes: + postgres-data: + ``` + +2. Configure your agent to use PostgreSQL by setting the database URL environment variable. + + * Using the `export` command: + + ```bash + export DATABASE_URL=postgres://kagent:kagent@localhost:5432/kagent + ``` + + * Adding it to your `.env` file: + + ```bash + echo "DATABASE_URL=postgres://kagent:kagent@localhost:5432/kagent" >> .env + ``` + +3. Start PostgreSQL and your agent. + + ```bash + docker-compose up -d postgres + kagent run + ``` + ## Troubleshooting If you run into any issues, you can start by checking the logs from the agent and/or MCP server containers. You can check the running containers using `docker ps` command and then use the `docker logs [container_id]` command to view the logs from individual container. diff --git a/src/app/docs/kagent/introduction/installation/page.mdx b/src/app/docs/kagent/introduction/installation/page.mdx index 313e7b0..04383c9 100644 --- a/src/app/docs/kagent/introduction/installation/page.mdx +++ b/src/app/docs/kagent/introduction/installation/page.mdx @@ -151,7 +151,11 @@ Another way to install kagent is using Helm. Review the following advanced configuration options that you might want to set up for your kagent installation. -### Configure the controller service name +### Configure controller environment variables + +You can configure the controller by using environment variables for settings such as service names, connection details, and more. + +#### Configure the controller service name By default, kagent uses `kagent-controller` as the controller service name when constructing URLs for agent deployments. If you need to customize this name, set the `KAGENT_CONTROLLER_NAME` environment variable on the controller pod. @@ -173,6 +177,47 @@ controller: value: my-kagent ``` +#### More environment variables + +You can add custom environment variables to the controller by using the `controller.env` field. + +**Helm `--set` flag:** + +```bash +helm install kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \ + --namespace kagent \ + --set controller.env[0].name=KAGENT_CONTROLLER_NAME \ + --set controller.env[0].value=my-kagent \ + --set controller.env[1].name=LOG_LEVEL \ + --set controller.env[1].value=debug +``` + +**Helm values file:** + +```yaml +controller: + env: + - name: KAGENT_CONTROLLER_NAME + value: my-kagent + - name: LOG_LEVEL + value: debug + - name: CUSTOM_VAR + value: custom-value +``` + +#### Using secrets for environment variables + +You can also reference Kubernetes secrets for environment variables by using the `envFrom` field in Helm. + +```yaml +controller: + envFrom: + - secretRef: + name: controller-secrets +``` + +This example loads all key-value pairs from the `controller-secrets` secret as environment variables in the controller pod. + ## Uninstallation Refer to the [Uninstall](/docs/kagent/operations/uninstall) guide. diff --git a/src/app/docs/kagent/operations/operational-considerations/page.mdx b/src/app/docs/kagent/operations/operational-considerations/page.mdx new file mode 100644 index 0000000..6c488c5 --- /dev/null +++ b/src/app/docs/kagent/operations/operational-considerations/page.mdx @@ -0,0 +1,137 @@ +--- +title: "Operational considerations" +pageOrder: 1 +description: "Important operational considerations when running kagent in production." +--- + +export const metadata = { + title: "Operational Considerations", + description: "Important operational considerations when running kagent in production.", + author: "kagent.dev" +}; + +# Operational considerations + +Review the following operational considerations when running kagent in production environments, including database configuration, high availability, and secret management. + +## Automatic agent restart on secret updates + +Kagent automatically restarts agents when you update the secrets that the agents reference. This restart ensures that agents pick up new API keys, TLS certificates, and other secret values without manual intervention. + +The following secret updates trigger automatic agent restarts: + +- **API keys**: Secrets referenced in `ModelConfig` resources (e.g., `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`) +- **TLS certificates**: Secrets referenced in `ModelConfig` TLS configuration (e.g., CA certificates) +- **Environment variables**: Any secrets referenced via `secretKeyRef` in agent deployment specifications + +## Leader election when controller is scaled + +When you scale the kagent controller to multiple replicas for high availability, leader election is automatically enabled. This ensures that only one controller instance actively reconciles resources at a time, preventing conflicts and duplicate operations. + +### Leader election scenarios + +- **Single replica**: No leader election needed; the single controller instance handles all operations +- **Multiple replicas**: Leader election is automatically enabled when `controller.replicas > 1` +- **Active leader**: Only the elected leader performs reconciliation operations +- **Standby replicas**: Other replicas remain ready but do not perform reconciliation until they become the leader + +### Enable high availability + +You can set the number of controller replicas to enable high availability. + +**Helm `--set` flag:** + +```bash +helm upgrade kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \ + --namespace kagent \ + --set controller.replicas=3 +``` + +**Helm values file:** + +```yaml +controller: + replicas: 3 +``` + +### More considerations for HA + +- **Database requirement**: When using multiple controller replicas, you must use PostgreSQL as the database backend. SQLite cannot be used with multiple replicas (see [SQLite database scaling limitation](#sqlite-database-scaling-limitation)). +- **Leader election**: Leader election uses Kubernetes leases and is handled automatically. +- **Failover**: If the leader fails, another replica automatically becomes the leader. + +## SQLite database scaling limitation + +SQLite is the default database for kagent and works well for single-replica controller deployments. However, SQLite cannot be used when scaling the controller to multiple replicas. + +SQLite is a file-based database that does not support concurrent writes from multiple processes. When you scale the controller to multiple replicas, each replica would try to access the same SQLite database file, causing conflicts and potential data corruption. + +If you try to scale the controller with SQLite enabled, you see an error during Helm installation or upgrade: + +```bash +Error: cannot scale controller with SQLite database +``` + +### Use PostgreSQL for scaling + +To scale the controller to multiple replicas, you must configure PostgreSQL as the database backend. You can enable PostgreSQL by using the Helm `--set` flag or values file. + +**Helm `--set` flag:** + +```bash +helm upgrade kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \ + --namespace kagent \ + --set database.type=postgres \ + --set database.postgres.url=postgres://user:password@postgres-host:5432/kagent \ + --set controller.replicas=3 +``` + +**Helm values file:** + +```yaml +database: + type: postgres + postgres: + url: postgres://user:password@postgres-host:5432/kagent + +controller: + replicas: 3 +``` + +### Migrate from SQLite to PostgreSQL + +If you're currently using SQLite and want to scale the controller, consider the following steps. + +1. Backup your data as needed, such as by copying the SQLite database file to a backup location. + + ```bash + kubectl exec -n kagent deployment/kagent-controller -c controller -- \ + sqlite3 /var/lib/kagent/kagent.db .dump > backup.sql + ``` + +2. Set up PostgreSQL by: + - Installing PostgreSQL in your cluster; or + - Using a managed PostgreSQL service. + +3. Update your Helm values to use PostgreSQL. + ```yaml + database: + type: postgres + postgres: + url: postgres://user:password@postgres-host:5432/kagent + ``` + +4. Upgrade the Helm release. + ```bash + helm upgrade kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \ + --namespace kagent \ + -f values.yaml + ``` + +5. Scale the controller. + ```bash + helm upgrade kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \ + --namespace kagent \ + -f values.yaml \ + --set controller.replicas=3 + ``` diff --git a/src/app/docs/kagent/operations/page.mdx b/src/app/docs/kagent/operations/page.mdx index d5241bf..fc9e1e9 100644 --- a/src/app/docs/kagent/operations/page.mdx +++ b/src/app/docs/kagent/operations/page.mdx @@ -19,6 +19,7 @@ import QuickLink from '@/components/quick-link';
+ diff --git a/src/app/docs/kagent/resources/cli/kagent-run/page.mdx b/src/app/docs/kagent/resources/cli/kagent-run/page.mdx index 0955155..fa42028 100644 --- a/src/app/docs/kagent/resources/cli/kagent-run/page.mdx +++ b/src/app/docs/kagent/resources/cli/kagent-run/page.mdx @@ -16,6 +16,7 @@ kagent run [project-directory] [flags] - `project-directory` - The directory containing the agent project (default: current directory) **Flags:** +- `--build` - Rebuild the Docker image before running - `--project-dir` - Project directory (default: current directory) **Global Flags:** @@ -29,6 +30,16 @@ kagent run [project-directory] [flags] The `kagent run` command runs an agent project locally using `docker-compose` and launches an interactive chat session. This way, you can test and interact with your agent before deploying it to a Kubernetes cluster. +### Rebuilding before running + +Use the `--build` flag to rebuild the Docker image before running the agent. This is useful when you've made changes to your agent code and want to test the updated version without manually running `kagent build` first. + +```bash +kagent run --build +``` + +This command rebuilds the agent image and then starts the interactive chat interface. It's equivalent to running `kagent build` followed by `kagent run`. + ## Example Run an agent project from the current directory: @@ -43,3 +54,11 @@ Run an agent project from a specific directory: kagent run ./my-agent ``` +Rebuild the image and run the agent: + +```bash +kagent run --build +``` + +This is useful after making code changes to ensure you're testing the latest version of your agent. + diff --git a/src/config/navigation.json b/src/config/navigation.json index 6b2703c..777f122 100644 --- a/src/config/navigation.json +++ b/src/config/navigation.json @@ -195,6 +195,11 @@ "href": "/docs/kagent/operations/debug", "description": "Find solutions to common issues and troubleshooting tips for kagent." }, + { + "title": "Operational considerations", + "href": "/docs/kagent/operations/operational-considerations", + "description": "Important operational considerations when running kagent in production." + }, { "title": "Upgrade kagent", "href": "/docs/kagent/operations/upgrade", From 30f445e4773e27d637bce487799e6f7f8df694e4 Mon Sep 17 00:00:00 2001 From: Art Date: Fri, 12 Dec 2025 13:05:08 -0500 Subject: [PATCH 2/5] Apply suggestions from code review Co-authored-by: Rachael Graham Signed-off-by: Art --- src/app/docs/kagent/examples/a2a-byo/page.mdx | 2 +- .../kagent/getting-started/local-development/page.mdx | 2 +- .../operations/operational-considerations/page.mdx | 11 +++++------ 3 files changed, 7 insertions(+), 8 deletions(-) diff --git a/src/app/docs/kagent/examples/a2a-byo/page.mdx b/src/app/docs/kagent/examples/a2a-byo/page.mdx index 126f197..c73df37 100644 --- a/src/app/docs/kagent/examples/a2a-byo/page.mdx +++ b/src/app/docs/kagent/examples/a2a-byo/page.mdx @@ -251,7 +251,7 @@ Lifespan hooks initialize or clean up tasks when your BYO agent starts up or shu To use lifespan hooks in your ADK agent, create a lifespan function and pass it to `KAgentApp`. -1. Create a lifespan function in your agent code, such as the following python example. The lifespan function is an async context manager that runs in either startup and shutdown code. +1. Create a lifespan function in your agent code, such as the following python example. The lifespan function is an async context manager that runs in either startup or shutdown code. - **Startup code** (before `yield`): Executes when the agent container starts. diff --git a/src/app/docs/kagent/getting-started/local-development/page.mdx b/src/app/docs/kagent/getting-started/local-development/page.mdx index 022bd5d..29d4cd2 100644 --- a/src/app/docs/kagent/getting-started/local-development/page.mdx +++ b/src/app/docs/kagent/getting-started/local-development/page.mdx @@ -265,7 +265,7 @@ You can now test the deployed agent and the MCP server through kagent UI. ## Using PostgreSQL for local development -By default, kagent uses SQLite for local development. For most local development, SQLite is sufficient and simpler to set up. However, you can also use PostgreSQL for local development, which is useful if you want to test with the same database backend that you use in production. +By default, kagent uses SQLite, which is sufficient for most local development and simpler to set up. However, you can also use PostgreSQL for local development, which is useful if you want to test with the same database backend that you use in production. The following steps show how to set up PostgreSQL with `docker-compose`. diff --git a/src/app/docs/kagent/operations/operational-considerations/page.mdx b/src/app/docs/kagent/operations/operational-considerations/page.mdx index 6c488c5..fab6b6f 100644 --- a/src/app/docs/kagent/operations/operational-considerations/page.mdx +++ b/src/app/docs/kagent/operations/operational-considerations/page.mdx @@ -30,10 +30,10 @@ When you scale the kagent controller to multiple replicas for high availability, ### Leader election scenarios -- **Single replica**: No leader election needed; the single controller instance handles all operations -- **Multiple replicas**: Leader election is automatically enabled when `controller.replicas > 1` -- **Active leader**: Only the elected leader performs reconciliation operations -- **Standby replicas**: Other replicas remain ready but do not perform reconciliation until they become the leader +- **Single replica**: No leader election needed; the single controller instance handles all operations. +- **Multiple replicas**: Leader election is automatically enabled when `controller.replicas > 1`. +- **Active leader**: Only the elected leader performs reconciliation operations. +- **Standby replicas**: Other replicas remain ready but do not perform reconciliation until they become the leader. ### Enable high availability @@ -64,7 +64,7 @@ controller: SQLite is the default database for kagent and works well for single-replica controller deployments. However, SQLite cannot be used when scaling the controller to multiple replicas. -SQLite is a file-based database that does not support concurrent writes from multiple processes. When you scale the controller to multiple replicas, each replica would try to access the same SQLite database file, causing conflicts and potential data corruption. +SQLite is a file-based database that does not support concurrent writes from multiple processes. When you scale the controller to multiple replicas, each replica tries to access the same SQLite database file, causing conflicts and potential data corruption. If you try to scale the controller with SQLite enabled, you see an error during Helm installation or upgrade: @@ -93,7 +93,6 @@ database: type: postgres postgres: url: postgres://user:password@postgres-host:5432/kagent - controller: replicas: 3 ``` From a9fa6af87c935d3e3d291d6855d39d1597407f14 Mon Sep 17 00:00:00 2001 From: Art Date: Mon, 15 Dec 2025 09:02:10 -0500 Subject: [PATCH 3/5] Update src/app/docs/kagent/getting-started/local-development/page.mdx Signed-off-by: Art --- src/app/docs/kagent/getting-started/local-development/page.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/app/docs/kagent/getting-started/local-development/page.mdx b/src/app/docs/kagent/getting-started/local-development/page.mdx index 29d4cd2..4dde6c4 100644 --- a/src/app/docs/kagent/getting-started/local-development/page.mdx +++ b/src/app/docs/kagent/getting-started/local-development/page.mdx @@ -265,7 +265,7 @@ You can now test the deployed agent and the MCP server through kagent UI. ## Using PostgreSQL for local development -By default, kagent uses SQLite, which is sufficient for most local development and simpler to set up. However, you can also use PostgreSQL for local development, which is useful if you want to test with the same database backend that you use in production. +By default, kagent uses in-memory database for storing session information, which is sufficient for most local development and simpler to set up. However, you can also use PostgreSQL for local development, which is useful if you want to test with the same database backend that you use in production. The following steps show how to set up PostgreSQL with `docker-compose`. From 7bc5bbc103c1ff5b37282f642526ef057b51e7ff Mon Sep 17 00:00:00 2001 From: Art Berger Date: Mon, 15 Dec 2025 09:04:05 -0500 Subject: [PATCH 4/5] rm sqlite Signed-off-by: Art Berger --- .../operational-considerations/page.mdx | 54 +------------------ 1 file changed, 2 insertions(+), 52 deletions(-) diff --git a/src/app/docs/kagent/operations/operational-considerations/page.mdx b/src/app/docs/kagent/operations/operational-considerations/page.mdx index fab6b6f..4998b92 100644 --- a/src/app/docs/kagent/operations/operational-considerations/page.mdx +++ b/src/app/docs/kagent/operations/operational-considerations/page.mdx @@ -56,25 +56,13 @@ controller: ### More considerations for HA -- **Database requirement**: When using multiple controller replicas, you must use PostgreSQL as the database backend. SQLite cannot be used with multiple replicas (see [SQLite database scaling limitation](#sqlite-database-scaling-limitation)). +- **Database requirement**: When using multiple controller replicas, use PostgreSQL as the database backend. The default in-memory database does not support multiple replicas. - **Leader election**: Leader election uses Kubernetes leases and is handled automatically. - **Failover**: If the leader fails, another replica automatically becomes the leader. -## SQLite database scaling limitation - -SQLite is the default database for kagent and works well for single-replica controller deployments. However, SQLite cannot be used when scaling the controller to multiple replicas. - -SQLite is a file-based database that does not support concurrent writes from multiple processes. When you scale the controller to multiple replicas, each replica tries to access the same SQLite database file, causing conflicts and potential data corruption. - -If you try to scale the controller with SQLite enabled, you see an error during Helm installation or upgrade: - -```bash -Error: cannot scale controller with SQLite database -``` - ### Use PostgreSQL for scaling -To scale the controller to multiple replicas, you must configure PostgreSQL as the database backend. You can enable PostgreSQL by using the Helm `--set` flag or values file. +To scale the controller to multiple replicas, configure PostgreSQL as the database backend. You can enable PostgreSQL by using the Helm `--set` flag or values file. **Helm `--set` flag:** @@ -96,41 +84,3 @@ database: controller: replicas: 3 ``` - -### Migrate from SQLite to PostgreSQL - -If you're currently using SQLite and want to scale the controller, consider the following steps. - -1. Backup your data as needed, such as by copying the SQLite database file to a backup location. - - ```bash - kubectl exec -n kagent deployment/kagent-controller -c controller -- \ - sqlite3 /var/lib/kagent/kagent.db .dump > backup.sql - ``` - -2. Set up PostgreSQL by: - - Installing PostgreSQL in your cluster; or - - Using a managed PostgreSQL service. - -3. Update your Helm values to use PostgreSQL. - ```yaml - database: - type: postgres - postgres: - url: postgres://user:password@postgres-host:5432/kagent - ``` - -4. Upgrade the Helm release. - ```bash - helm upgrade kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \ - --namespace kagent \ - -f values.yaml - ``` - -5. Scale the controller. - ```bash - helm upgrade kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \ - --namespace kagent \ - -f values.yaml \ - --set controller.replicas=3 - ``` From 2af4644d21b7044dde30ef3887e30d7fe36a3524 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Thu, 18 Dec 2025 09:32:05 -0500 Subject: [PATCH 5/5] rm section Signed-off-by: Art Berger --- .../local-development/page.mdx | 46 ------------------- 1 file changed, 46 deletions(-) diff --git a/src/app/docs/kagent/getting-started/local-development/page.mdx b/src/app/docs/kagent/getting-started/local-development/page.mdx index 4dde6c4..10f59b3 100644 --- a/src/app/docs/kagent/getting-started/local-development/page.mdx +++ b/src/app/docs/kagent/getting-started/local-development/page.mdx @@ -263,52 +263,6 @@ mcpserver.kagent.dev/server-everything True 112s You can now test the deployed agent and the MCP server through kagent UI. -## Using PostgreSQL for local development - -By default, kagent uses in-memory database for storing session information, which is sufficient for most local development and simpler to set up. However, you can also use PostgreSQL for local development, which is useful if you want to test with the same database backend that you use in production. - -The following steps show how to set up PostgreSQL with `docker-compose`. - -1. Add PostgreSQL service to your `docker-compose.yaml`. - - ```yaml - services: - postgres: - image: postgres:15-alpine - environment: - POSTGRES_USER: kagent - POSTGRES_PASSWORD: kagent - POSTGRES_DB: kagent - ports: - - "5432:5432" - volumes: - - postgres-data:/var/lib/postgresql/data - - volumes: - postgres-data: - ``` - -2. Configure your agent to use PostgreSQL by setting the database URL environment variable. - - * Using the `export` command: - - ```bash - export DATABASE_URL=postgres://kagent:kagent@localhost:5432/kagent - ``` - - * Adding it to your `.env` file: - - ```bash - echo "DATABASE_URL=postgres://kagent:kagent@localhost:5432/kagent" >> .env - ``` - -3. Start PostgreSQL and your agent. - - ```bash - docker-compose up -d postgres - kagent run - ``` - ## Troubleshooting If you run into any issues, you can start by checking the logs from the agent and/or MCP server containers. You can check the running containers using `docker ps` command and then use the `docker logs [container_id]` command to view the logs from individual container.