diff --git a/docs/deploy/agent-runtime/agents-cli.md b/docs/deploy/agent-runtime/agents-cli.md index 7e71c8d0e..1e74aa4dc 100644 --- a/docs/deploy/agent-runtime/agents-cli.md +++ b/docs/deploy/agent-runtime/agents-cli.md @@ -1,6 +1,6 @@ # Deploy to Agent Runtime with agents-cli -
+
Supported in ADKPython
diff --git a/docs/deploy/agent-runtime/deploy.md b/docs/deploy/agent-runtime/deploy.md index aacefb651..b88408adb 100644 --- a/docs/deploy/agent-runtime/deploy.md +++ b/docs/deploy/agent-runtime/deploy.md @@ -1,7 +1,7 @@ # Deploy to Agent Runtime -
- Supported in ADKPython +
+ Supported in ADKPythonGo v1.2.0
This deployment procedure describes how to perform a standard deployment of @@ -110,16 +110,30 @@ With your Google Cloud and coding environment prepared, you're ready to deploy your agent. The instructions assume that you have an agent project folder, such as: -```shell -multi_tool_agent/ -├── .env -├── __init__.py -└── agent.py -``` -For more details on the project files and format, see the -[multi_tool_agent](https://github.com/google/adk-docs/tree/main/examples/python/snippets/get-started/multi_tool_agent) -code sample. +=== "Python" + + ```shell + multi_tool_agent/ + ├── .env + ├── __init__.py + └── agent.py + ``` + + For more details on the project files and format, see the + [multi_tool_agent](https://github.com/google/adk-docs/tree/main/examples/python/snippets/get-started/multi_tool_agent) + code sample. + + +=== "Go" + ```shell + multi_tool_agent/ + ├── go.mod + ├── go.sum + └── main.go + ``` + + ## Deploy the agent {#deploy-agent} @@ -130,35 +144,85 @@ managed Agent Runtime service. This process can take several minutes. The following example deploy command uses the `multi_tool_agent` sample code as the project to be deployed: -```shell -PROJECT_ID=my-project-id -LOCATION_ID=us-central1 - -adk deploy agent_engine \ - --project=$PROJECT_ID \ - --region=$LOCATION_ID \ - --display_name="My First Agent" \ - multi_tool_agent -``` +=== "Python" + + ```shell + PROJECT_ID=my-project-id + LOCATION_ID=us-central1 + + adk deploy agent_engine \ + --project=$PROJECT_ID \ + --region=$LOCATION_ID \ + --display_name="My First Agent" \ + multi_tool_agent + ``` + +=== "Go" + + ```shell + PROJECT_ID=my-project-id + LOCATION_ID=us-central1 + + adkgo deploy agentengine \ + -e ./main.go \ + -s "multi_tool_agent" \ + -p $PROJECT_ID \ + -r $LOCATION_ID \ + -d . + ``` + For `region`, you can find a list of the supported regions on the [Agent Builder locations page](https://docs.cloud.google.com/agent-builder/locations#supported-regions-agent-engine). -To learn about the CLI options for the `adk deploy agent_engine` command, see the -[ADK CLI Reference](/api-reference/cli/#adk-deploy-agent-engine). + +=== "Python" + + To learn about the CLI options for the `adk deploy agent_engine` command, see the + [ADK CLI Reference](/api-reference/cli/#adk-deploy-agent-engine). + +=== "Go" + + To learn about the CLI options for the `adkgo deploy agentengine` command you can run `adkgo help deploy agentengine` which will display available options. + The most important are: + ```shell + -e, --entry_point_path string Path to an entry point (go 'main') + -s, --name string Agent Engine name + -p, --project_name string GCP Project Name + -r, --region string GCP Region + -d, --source_dir string Directory to archive, defaults to current working directory + ``` + ### Deploy command output Once successfully deployed, you should see the following output: -```shell -Creating AgentEngine -Create AgentEngine backing LRO: projects/123456789/locations/us-central1/reasoningEngines/751619551677906944/operations/2356952072064073728 -View progress and logs at https://console.cloud.google.com/logs/query?project=hopeful-sunset-478017-q0 -AgentEngine created. Resource name: projects/123456789/locations/us-central1/reasoningEngines/751619551677906944 -To use this AgentEngine in another session: -agent_engine = vertexai.agent_engines.get('projects/123456789/locations/us-central1/reasoningEngines/751619551677906944') -Cleaning up the temp folder: /var/folders/k5/pv70z5m92s30k0n7hfkxszfr00mz24/T/agent_engine_deploy_src/20251219_134245 -``` +=== "Python" + ```shell + Creating AgentEngine + Create AgentEngine backing LRO: projects/123456789/locations/us-central1/reasoningEngines/751619551677906944/operations/2356952072064073728 + View progress and logs at https://console.cloud.google.com/logs/query?project=hopeful-sunset-478017-q0 + AgentEngine created. Resource name: projects/123456789/locations/us-central1/reasoningEngines/751619551677906944 + To use this AgentEngine in another session: + agent_engine = vertexai.agent_engines.get('projects/123456789/locations/us-central1/reasoningEngines/751619551677906944') + Cleaning up the temp folder: /var/folders/k5/pv70z5m92s30k0n7hfkxszfr00mz24/T/agent_engine_deploy_src/20251219_134245 + ``` + +=== "Go" + ```shell + Computing flags & preparing temp : Starting + + ... + + > [Deployed Reasoning Engine: projects/887748635400/locations/us-central1/reasoningEngines/751619551677906944] + > [Display Name: simpleText] + + Deploying to Agent Engine : Finished successfully + Cleaning temp : Starting + > [Clean temp starting with /tmp/agentEngine_20260424_141040__2470352066] + + Cleaning temp : Finished successfully + ``` Note that you now have a `RESOURCE_ID` where your agent has been deployed (which in the example above is `751619551677906944`). You need this ID number along diff --git a/docs/deploy/agent-runtime/index.md b/docs/deploy/agent-runtime/index.md index 0d56d042f..792d1b937 100644 --- a/docs/deploy/agent-runtime/index.md +++ b/docs/deploy/agent-runtime/index.md @@ -1,7 +1,7 @@ # Deploy to Agent Runtime -
- Supported in ADKPython +
+ Supported in ADKPythonGo v1.2.0
Google Cloud Agent Platform @@ -39,12 +39,27 @@ purposes: ## Deployment payload {#payload} -When you deploy your ADK agent project to Agent Runtime, the following content is -uploaded to the service: -- Your ADK agent code -- Any dependencies declared in your ADK agent code +=== "Python" -The deployment *does not* include the ADK API server or the ADK web user -interface libraries. The Agent Runtime service provides the libraries for ADK API -server functionality. + When you deploy your ADK agent project to Agent Runtime, the following content is + uploaded to the service: + + - Your ADK agent code + - Any dependencies declared in your ADK agent code + + The deployment *does not* include the ADK API server or the ADK web user + interface libraries. The Agent Runtime service provides the libraries for ADK API + server functionality. + +=== "Go" + + When you deploy your ADK project to Agent Runtime, the following content is uploaded to the server: + + - Your ADK project source code + + Please mind that Agent Runtime has its own API for querying the agent. All you have to do is use a dedicated launcher: + ```go + l := agentengine.NewLauncher(agentEngineID) + err := l.Execute(ctx, config, os.Args[1:]) + ``` diff --git a/docs/deploy/agent-runtime/methods.md b/docs/deploy/agent-runtime/methods.md new file mode 100644 index 000000000..3458093ec --- /dev/null +++ b/docs/deploy/agent-runtime/methods.md @@ -0,0 +1,328 @@ +# Supported methods + +## Summary + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Method + + Description + + Reference + + Support +
+ Python + + Go + + Java +
Session management +
create_sessionDeprecated, use async_create_session instead✅❌❌
async_create_session✅✅❌
async_get_session✅✅❌
async_list_sessions✅✅❌
async_delete_session✅✅❌
get_session✅✅❌
list_sessions✅✅❌
delete_session✅✅❌
async_get_session✅✅❌
async_list_sessions✅✅❌
async_create_session✅✅❌
async_delete_session✅✅❌
Memory +
async_add_session_to_memory✅✅❌
async_search_memory✅✅❌
Query +
stream_query✅✅❌
async_stream_query✅✅❌
streaming_agent_run_with_events✅✅❌
Others +
register_feedback✅✅❌
+ +# AIPlatform API for Agent Engine +## Calling the Agent Engine methods +### AIPlatform AgentEngine Input +Input is JSON formatted according to the following schema. +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://google.com/agentengine/aiplatform.json", + "title": "AgentEngine wrapper for AIPlatform", + "description": "", + "type": "object", + "properties": { + "class_method": { + "description": "Name of the underlying method", + "type": "string" + }, + "input": { + "description": "Method-specific input", + "type": "object" + }, + }, + "required": [ + "class_method", + "input" + ] +} +``` +### Response for streaming +For early failures, before the streaming starts, the response is just like the one for [non-streaming version](#response-for-non-streaming) + +After the streaming starts, it provides a stream of JSON-formatted data one per line. JSON object is specific for the called method. +In case of an error, the HTTP status is already 200 and cannot be changed, so the error is formatted as an streaming data as well, according to the schema: +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://google.com/agentengine/streaming_error.json", + "title": "Defines how streaming errors are formatted", + "description": "", + "type": "object", + "properties": { + "error": { + "description": "Object describing the error", + "type": "object" + }, + }, + "required": [ + "error" + ] +} +``` + +### Response for non-streaming +On success, the response is JSON-formatted response specific for the called method (class_method). + +On failure, the response is JSON-formatted error similar to the following one: +```json +{ + "error": { + "code": 400, + "message": "Reasoning Engine Execution failed.\nPlease refer to our documentation (https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/troubleshooting/use) for checking logs and other troubleshooting tips.\nError Details: {\"detail\":\"Agent Engine Error: An error occurred during invocation. Exception: 404 NOT_FOUND. {'error': {'code': 404, 'message': 'Session projects/kdroste-adk-2025-12/locations/us-central1/reasoningEngines/3765669545214214144/sessions/7177615616973471745 not found.', 'status': 'NOT_FOUND'}}\\nRequest Data: {'session_id': '7177615616973471745', 'user_id': 'u_12345_non_existing'}\"}", + "status": "FAILED_PRECONDITION", + "details": [ + { + "@type": "type.googleapis.com/google.rpc.DebugInfo", + "detail": "[ORIGINAL ERROR] generic::failed_precondition: Reasoning Engine Execution failed.\nPlease refer to our documentation (https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/troubleshooting/use) for checking logs and other troubleshooting tips.\nError Details: {\"detail\":\"Agent Engine Error: An error occurred during invocation. Exception: 404 NOT_FOUND. {'error': {'code': 404, 'message': 'Session projects/kdroste-adk-2025-12/locations/us-central1/reasoningEngines/3765669545214214144/sessions/7177615616973471745 not found.', 'status': 'NOT_FOUND'}}\\nRequest Data: {'session_id': '7177615616973471745', 'user_id': 'u_12345_non_existing'}\"} [google.rpc.error_details_ext] { message: \"Reasoning Engine Execution failed.\\nPlease refer to our documentation (https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/troubleshooting/use) for checking logs and other troubleshooting tips.\\nError Details: {\\\"detail\\\":\\\"Agent Engine Error: An error occurred during invocation. Exception: 404 NOT_FOUND. {\\'error\\': {\\'code\\': 404, \\'message\\': \\'Session projects/kdroste-adk-2025-12/locations/us-central1/reasoningEngines/3765669545214214144/sessions/7177615616973471745 not found.\\', \\'status\\': \\'NOT_FOUND\\'}}\\\\nRequest Data: {\\'session_id\\': \\'7177615616973471745\\', \\'user_id\\': \\'u_12345_non_existing\\'}\\\"}\" }" + } + ] + } +} +``` + + + + +# Create session +You should use `async_create_session`. `create_session` is deprecated. + +## `async_create_session` +### Input +Input adheres to the general [schema](#aiplatform-agentengine-input) : +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://google.com/agentengine/async_create_session.schema.json", + "title": "Request for async_create_session", + "description": "", + "type": "object", + "properties": { + "user_id": { + "description": "UserID", + "type": "string" + }, + "state": { + "description": "Dictionary mapping string to objects", + "type": "object" + }, + }, + "required": [ + "user_id" + ] +} +``` + +### Semantics +Creates a new session + +### Output +Session data is returned + +#TODO(kdroste): create a schema for that +```go +type SessionData struct { + UserID string `json:"user_id"` + LastUpdateTime float64 `json:"last_update_time"` + AppName string `json:"app_name"` + ID string `json:"id"` + State map[string]any `json:"state"` + Events []session.Event `json:"events"` +} +``` + +### Error handling +In case of a failure and error is returned using the non-streaming version of [response](#response-for-non-streaming) + +### Invocation examples + +```bash +curl -v \ +-H "Authorization: Bearer $(gcloud auth print-access-token)" \ +-H "Content-Type: application/json" \ +https://${LOCATION_ID}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION_ID}/reasoningEngines/${RESOURCE_ID}:query -d '{ + "class_method": "async_create_session", + "input": { + "user_id": "u_12345", + } +}' +``` \ No newline at end of file diff --git a/docs/deploy/agent-runtime/test.md b/docs/deploy/agent-runtime/test.md index df5fb13cf..ee3685a7a 100644 --- a/docs/deploy/agent-runtime/test.md +++ b/docs/deploy/agent-runtime/test.md @@ -36,8 +36,9 @@ To find your project information with Google Cloud Console: 1. In the Google Cloud Console, navigate to the Agent Runtime page: [https://console.cloud.google.com/vertex-ai/agents/agent-engines](https://console.cloud.google.com/vertex-ai/agents/agent-engines) -1. At the top of the page, select **API URLs**, and then copy the **Query - URL** string for your deployed agent, which should be in this format: +1. Choose the right instance + +1. At the top of the page, select **Copy query URL**, which should be in this format: https://$(LOCATION_ID)-aiplatform.googleapis.com/v1/projects/$(PROJECT_ID)/locations/$(LOCATION_ID)/reasoningEngines/$(RESOURCE_ID):query @@ -189,6 +190,10 @@ To test interaction with the deployed agent via REST: }' ``` + + + + This request should generate a response from your deployed agent code in JSON format. For more information about interacting with a deployed ADK agent in Agent Runtime using REST calls, see diff --git a/mkdocs.yml b/mkdocs.yml index 99e0d446c..29c5281a2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -340,6 +340,7 @@ nav: - Standard deployment: deploy/agent-runtime/deploy.md - agents-cli: deploy/agent-runtime/agents-cli.md - Test deployed agents: deploy/agent-runtime/test.md + - Supported methods: deploy/agent-runtime/methods.md - Cloud Run: deploy/cloud-run.md - GKE: deploy/gke.md - Observability: