Currently there are several ways to setup and run an ADK system, there's limited cross-compatibility due to file structure requirements, and simplifying the deployment technique will reduce bloat.

Currently the documentation talks about the following ways to setup and run:

$adk <command>

https://google.github.io/adk-docs/get-started/quickstart/#run-your-agent
Requires this structure:

parent_folder/      
    multi_tool_agent/
        __init__.py
        agent.py
        .env

google.adk.runners

Here
Uses asyncio.run() and requires the end user to manage an event loop, moves project files out to the parent directory

Agent Engine

Here
Has the same directory structure as the adk <command> deployment, but requires a wrapper:

from vertexai.preview import reasoning_engines
app = reasoning_engines.AdkApp(
    agent=root_agent,
    enable_tracing=True,
)

Also the fact that deployment and testing is done through the agent_engines.create python command seems very Jupiter inspired instead of having an adk deploy agent_engine command or something.

get_fast_api_app - Cloud Run/GKE deployment

Here
Deploying to Cloud Run requires a different directory structure and introduces the get_fast_api_app function. Notably, this deployment setup is not compatible with using the $adk <command> framework or Agent Engine deployment.

your-project-directory/
├── capital_agent/
│   ├── __init__.py
│   └── agent.py       # Your agent code (see "Agent sample" tab)
├── main.py            # FastAPI application entry point
├── requirements.txt   # Python dependencies
└── Dockerfile         # Container build instructions

Summary

There are 3 different directory structures and code paths depending on what your final deployment is going to look like, and this isn't mentioned in the Get Started section. So what happened in my case was that I:

• Created an application that I could use adk web with for testing
• All the following tutorials started using runners and sessions, so reorganized the code structure and implemented asyncio.run()
• I then looked at deployment options and saw that there was the get_fast_api_app() function, which simplified setup and deployment by handling the event loop and runner/session setup, so I reorganized my code again.
• I'm now at the point where we may decide to deploy this to Agent Engine instead of Cloud Run, and the get_fast_api_app is not compatible with it, so I'm going to have to refactor the code back to the $adk <command> structure

My proposal to streamline this is to have all documentation use the get_fast_api_app() syntax and have a 'normal' directory structure where the project setup files (.env and requirements.txt) are in the parent directory. The adk commands should use the get_fast_api_app under the hood and support using either variables in a .env file or command line args for the setup. For VertexAI Agent Engine deployment, there should be a $adk deploy agent_engine command that works.

For instances where people need more direct access to runners or sessions, there can be a dedicated area that talks about advanced setup, or people can look at the get_fast_api_app function and use that as guidance for their own setup. This could also be set up as a class instead of a function so that people can override the __init__ function to introduce their own behavior, or set up their own class that inherits from this one.

Context

One of the things I would like to see is standardizing how the application is deployed, especially in the docs.

So far there seems to be: adk web - local hosting, but you can also deploy it this way using the get_fast_api_app from google.adk.cli.fast_api -> our preferred way if you're deploying through Agent Engine, then you use vertexai.agent_engines and the config is different You can deploy using the runner and do the fast_api setup more explicitly

There's also the difference between deploying the app using VertexAI and gcloud CLI authentication, and deploying the app using a Gemini API key, which is annoying because the models are not the same between the two (specifically for embedding as that's the use case that messed me up).

@dylan-apex great feedback. Do you mind creating a issue for us to track? Thanks.

Originally posted by @hangfei in #2133