Building an agent with ADK Go

In this Codelab, you'll build your very own agent using the Agent Development Kit (ADK) and deploy it to Google Cloud.

By the end of the lab, you will have gone through scaffolding a new ADK agent project, giving an agent different sets of tools, debugging behaviour locally using the ADK WebUI and deploying the agent to Cloud Run.

To get started, we'll scaffold a new agent project. We'll do this through the agent starter pack skill that ships with the platform. The skill guides you through template selection and scaffolds a basic base agent with the minimum setup necessary to be deployable on Google Cloud. From there, it can be extended with custom tools and tailored to your own use case.

🤖 Ask your coding agent:

I want to build a new agent. Help me get started using the agent starter pack.

Note

For this lab, you must pick the the Arena Agent template. This is the required template to be able to enter your agent into the arena.

What was created?

agent/
├── infra/
│   ├── main.tf                # Terraform entrypoint and provider configurations
│   ├── reasoning_engine.tf    # Reasoning engine deployment details (for managed sessions)
│   ├── cloudrun.tf            # CloudRun deployment details
│   ├── apis.tf                # Enabling required APIs
│   └── variables.tf           # Terraform variables
├── Dockerfile                 # Container image for buiding the artifact
├── go.mod                     # Project dependency file
└── main.go                    # Main agent application logic and entrypoint

Model Configuration

This is where we tell the agent which LLM to use. Here we configure it to use gemini-3.5-flash-lite via Vertex AI, pointing at the project and location our service is running in.

model, err := gemini.NewModel(ctx, "gemini-3.5-flash-lite", &genai.ClientConfig{
    Backend:  genai.BackendVertexAI,
    Project:  projectID,
    Location: "eu",
})
if err != nil {
    log.Fatalf("Failed to create model: %v", err)
}
agentConfig.Model = model

Session Management Configuration

Sessions keep track of the ongoing conversation between a user and the agent. Locally, we use a simple in-memory session service, since there's nothing to persist between restarts. When deployed, we instead use Vertex AI's managed session service, backed by the reasoning engine, so conversation state persists across requests and instances.

if isLocal() {
    launcherConfig.SessionService = session.InMemoryService()
} else {
    sessionService, err := sessionvertexai.NewSessionService(
        ctx,
        sessionvertexai.VertexAIServiceConfig{
            ProjectID:       projectID,
            Location:        location,
            ReasoningEngine: agentEngineID,
        },
        option.WithEndpoint(fmt.Sprintf("%s-aiplatform.googleapis.com:443", location)),
    )
    if err != nil {
        log.Fatalf("Failed to create session service: %v", err)
    }
    launcherConfig.SessionService = sessionService
}

Launcher Configuration

The launcher wires everything together and exposes the agent over HTTP. It combines the ADK WebUI, a REST API, and an A2A (Agent-to-Agent) launcher, so the same agent can be driven interactively, called as an API, or invoked via A2A. Locally we enable the webui and api commands so we can use the ADK WebUI for debugging (see next section). Once deployed, only the a2a endpoint is exposed.

webLauncher := web.NewLauncher(
    webui.NewLauncher(),
    webapi.NewLauncher(),
    weba2a.NewLauncher(),
)
launchArgs := []string{"--port", "8080"}
if isLocal() {
    launchArgs = append(launchArgs, []string{"webui", "api"}...)
}
launchArgs = append(launchArgs, []string{"a2a", "--a2a_agent_url", service}...)
if _, err := webLauncher.Parse(launchArgs); err != nil {
    log.Fatalf("webLauncher.Parse() error = %v", err)
}
if err := webLauncher.Run(context.Background(), launcherConfig); err != nil {
    log.Fatalf("webLauncher.Run() error = %v", err)
}

ADK ships with a local web UI purpose-built for debugging agent behaviour. Running our agent through it gives us visibility into what's actually happening under the hood: the back-and-forth of the conversation, and (as we'll see in later sections) the tool calls our agent makes along the way. It's the fastest way to poke at our agent and see how it behaves before deploying it anywhere.

Warning

Before running this step, make you have set the local environment credentials.

Run the ADK WebUI Playground

Run the following command in your terminal:

make run

Try it out

• Navigate to http://localhost:8080 in your browswer
• Send a prompt or instruction, e.g. "Hello, how are you?"

Now that we have been able to successfully interact with our agent locally, the next step is to deploy the agent onto the Cloud. This is made possible through the infra folder that was scaffolded alongside the agent. This folder declares (using Terraform) the infrastructure resources required by the agent.

🤖 Ask your coding agent:

I've verified my agent locally using the ADK Web UI. Please proceed to build and deploy my service

Your coding agent will run the Build and Deploy steps on your behalf.

Note

After each of the next steps in this Codelab, it is recommended to test your agent in the ADK WebUI to confirm it's behaving as expected before moving on. Once you're happy with it, commit your changes and ask your coding agent to build and redeploy the service so the update is live.

On its own, an agent can only reason over the language model's built-in knowledge and produce text. A tool is what lets it break out of that boundary and take action, e.g. calling an external service or API, fetching live or private data, performing a calculation, or triggering a side effect in another system. By giving our agent tools, we turn it from something that can only talk about a task into something that can actually go and do it.

Let's add a tool to our agent.

🤖 Ask your coding agent:

I'd like to add a tool to my ADK Go agent. This tool should be called `get_weather` and should take in the name of the city for which to retrieve the weather. The response should return the current temperature (in Celsius) for the requested city. Use the Open-Meteo API to retrieve the weather information, which is free and requires no API keys.

While a tool lets an agent reach out and take action, a skill shapes how the agent behaves. Skills package up instructions, context, or a particular workflow so the agent can reliably perform a specific kind of task on demand. Skills are a good fit for capabilities that are more about behavior, processes and domain knowledge.

Let's add a skill to our agent.

🤖 Ask your coding agent:

I'd like to add a skill to my ADK Go agent. This skill should be called `tell_joke` and should return a short, family-friendly joke when invoked.

An LLM's knowledge is frozen at its training cut-off, so on its own it can't know about anything that happened after that point. ADK ships a specialised, built-in GoogleSearch tool that solves this. This tool lets the agent ground its responses in real, up-to-date data by searching the web, much like a human would. Adding it to our agent gives it access to current knowledge, rather than relying solely on what it learned during training.

Let's add the GoogleSearch tool to our agent.

🤖 Ask your coding agent:

I'd like to add the built-in ADK `GoogleSearch` tool to my ADK Go agent so it can ground its responses in real-time, up-to-date information from the web.

LLMs are great at reasoning, but complex analyses and calculations are more reliably performed programmatically, for example by running a Python program, rather than worked out in the model's "brain". ADK ships a built-in CodeExecution tool for this. This tool lets the agent generate code and run it in an isolated, sandboxed Google Compute VM, then returns the generated result. This means our agent doesn't need to perform complex computations in memory. Instead, it can hand them off to a real interpreter and use the actual result.

Let's add the CodeExecution tool to our agent.

🤖 Ask your coding agent:

I'd like to add the built-in ADK `CodeExecution` tool to my ADK Go agent so it can generate and run code in a sandboxed environment for complex calculations and analyses.

Congratulations, you just built and deployed an ADK agent on Google Cloud!