> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
title: Deploy a serverless endpoint to Cloud Run
description: Generate, deploy, validate, and sync an AGNT5 serverless service on Cloud Run with Python or Go.
last_verified: 2026-08-26
---

A **Cloud Run revision** is an immutable release of a containerized HTTP service. AGNT5 uses the revision name as the serverless service version while Cloud Run owns scaling, ingress, and rollback.

The generated Python and Go services listen on Cloud Run's `PORT` and expose the signed AGNT5 protocol on `0.0.0.0`.

## 1. Generate the service

Choose the runtime already used by your project.

### Python

```bash
agnt5 serverless init \
  --provider cloud-run \
  --runtime python \
  --name orders-api

uv add agnt5 fastapi uvicorn
```

The generated `agnt5_serverless.py` exports a FastAPI `app` and reads `K_REVISION` for the immutable service version. It scaffolds one placeholder `hello` workflow — replace it with your own components by passing them to `serve()`:

```python
from myapp.workflows import my_workflow
from myapp.agents import my_agent
from myapp.tools import my_tool

agnt5_workerless = serve(
    service_name="orders-api",
    service_version=os.getenv("K_REVISION") or os.getenv("GIT_SHA", "local"),
    workflows=[my_workflow],
    agents=[my_agent],
    tools=[my_tool],
    signing_secret=lambda: os.getenv("AGNT5_SERVERLESS_SIGNING_SECRET"),
)
```

Omitting `workflows`/`tools`/`agents` falls back to whatever is registered globally via `@workflow`, `@tool`, and `@agent` decorators; passing explicit lists is more predictable in a serverless entrypoint that doesn't otherwise import your modules.

### Go

```bash
agnt5 serverless init \
  --provider cloud-run \
  --runtime go \
  --name orders-api

go get github.com/agnt5dev/sdk-go/serverless
```

The generated `cmd/agnt5-serverless/main.go` implements the same protocol with `net/http`.

## 2. Configure signing

1. Generate the shared HMAC secret. Use `printf` rather than shell redirection — `openssl rand -base64 32 > file` appends a trailing newline that Secret Manager preserves byte-for-byte, while `$(cat file)` used later to export the secret strips it, producing two different secret values and signature failures:

   ```bash
   ( umask 077 && printf '%s' "$(openssl rand -base64 32)" > .agnt5-serverless-secret )
   ```

2. Enable Secret Manager and store the value:

   ```bash
   gcloud services enable secretmanager.googleapis.com
   gcloud secrets create agnt5-serverless-signing-secret \
     --data-file=.agnt5-serverless-secret
   ```

3. Grant the Cloud Run service identity access to the secret. A `--source` deploy with no `--service-account` flag runs as the project's default compute service account:

   ```bash
   PROJECT_NUMBER="$(gcloud projects describe "$(gcloud config get-value project)" --format='value(projectNumber)')"

   gcloud secrets add-iam-policy-binding agnt5-serverless-signing-secret \
     --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
     --role="roles/secretmanager.secretAccessor"
   ```

4. Map the secret to `AGNT5_SERVERLESS_SIGNING_SECRET` during deployment.

Do not place the signing value in source, a Dockerfile, or a command committed to shell history.

## 3. Deploy from source

`--region` is required unless the project has a default set via `gcloud config set run/region <region>`.

### Python

```bash
gcloud run deploy orders-api \
  --source . \
  --region <region> \
  --allow-unauthenticated \
  --set-build-env-vars 'GOOGLE_ENTRYPOINT=uvicorn agnt5_serverless:app --host 0.0.0.0 --port 8080' \
  --set-secrets AGNT5_SERVERLESS_SIGNING_SECRET=agnt5-serverless-signing-secret:latest
```

### Go

```bash
gcloud run deploy orders-api \
  --source . \
  --region <region> \
  --allow-unauthenticated \
  --set-build-env-vars GOOGLE_BUILDABLE=./cmd/agnt5-serverless \
  --set-secrets AGNT5_SERVERLESS_SIGNING_SECRET=agnt5-serverless-signing-secret:latest
```


> The AGNT5 control plane does not mint Google identity tokens for endpoint calls. The Cloud Run ingress must accept unauthenticated HTTP requests, while the invoke route remains protected by AGNT5 HMAC. The manifest route is public.


## 4. Validate the revision

Read the deployed URL and immutable revision name:

```bash
ENDPOINT="$(gcloud run services describe orders-api --region <region> --format='value(status.url)')"
REVISION="$(gcloud run services describe orders-api --region <region> --format='value(status.latestReadyRevisionName)')"

agnt5 serverless validate "$ENDPOINT"
```

Validation checks the manifest shape and component declarations. It does not change routing.

## 5. Sync and activate

`agnt5 serverless sync` requires the local directory to be linked to an AGNT5 project (a `.agnt5/project-ref` file). If this directory hasn't been linked yet, run `agnt5 init` (or `agnt5 link <project-id>` to attach an existing project) first.

```bash
export AGNT5_SERVERLESS_SIGNING_SECRET="$(cat .agnt5-serverless-secret)"

agnt5 serverless sync "$ENDPOINT" \
  --provider cloud-run \
  --immutable-ref "$REVISION" \
  --signing-secret-env AGNT5_SERVERLESS_SIGNING_SECRET \
  --activate=false
```

Run **`agnt5 serverless status --deployment-id <deployment-id> --verify`** before repeating sync with `--activate=true`.

## Next steps

- [Serverless support matrix](/docs/run/serverless-support-matrix.md): compare tested hosts, runtimes, and remaining gaps.
- [Integrate Python web frameworks](/docs/integrations/python-web-frameworks.md): mount the Python adapter in an existing application.
- [Build a serverless endpoint in Go](/docs/integrations/go-serverless.md): register Go functions, tools, and agents.
- [Operate serverless endpoints](/docs/run/operate-serverless-endpoints.md): verify, promote, disable, and roll back revisions.