Use an agent

Using the Agent Platform SDK

When using the Agent Platform SDK, the code for querying an agent is the same regardless of whether it is running locally or deployed remotely. As the set of supported operations varies across frameworks, we provide usage instructions for framework-specific templates:

Framework Description
Agent Development Kit Designed based on Google's internal best practices for developers building AI applications or teams needing to rapidly prototype and deploy robust agent-based solutions.
Agent2Agent (preview) The Agent2Agent (A2A) protocol is an open standard designed to enable seamless communication and collaboration between AI agents.
LangChain Easier to use for basic use cases because of its predefined configurations and abstractions.
LangGraph Graph-based approach to defining workflows, with advanced human-in-the-loop and rewind/replay capabilities.
AG2 (formerly AutoGen) AG2 provides multi-agent conversation framework as a high-level abstraction for building LLM workflows.
LlamaIndex (preview) LlamaIndex's query pipeline offers a high-level interface for creating Retrieval-Augmented Generation (RAG) workflows.
Custom Agents that were developed and deployed without the use of a framework-specific template.

Use agents served on localhost

If you serve agents through an API server that are listening for requests on http://localhost:PORT_NUMBER, then you would send requests to

http://localhost:PORT_NUMBER/API_PATH

where

  • PORT_NUMBER is the port number that the server is listening on (e.g. 8080)
  • API_PATH is the path of the corresponding API endpoint (such as run or run_sse)

Use deployed agents through their underlying API

If you have deployed an agent, then you would send requests to the corresponding endpoint:

https://LOCATION-aiplatform.googleapis.com/reasoningEngines/v1/projects/PROJECT_NUMBER/locations/<var>LOCATION</var>/reasoningEngines/RESOURCE_ID/api/API_PATH

where

  • PROJECT_ID is the Google Cloud project ID where you deployed the agent
  • LOCATION is the region where the agent is deployed
  • RESOURCE_ID is the ID of the deployed agent as a reasoningEngine resource
  • API_PATH is the path of the corresponding API endpoint

This endpoint is equivalent to replacing the localhost base URL with the deployed agent base URL.

To give a few examples, if you deployed the ADK API server from a Dockerfile or Container Image, invoke the API endpoints as follows:

Run agent (single response) 

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/api/run -d '{
  "appName": "my_sample_agent",
  "userId": "u_123",
  "sessionId": "s_abc",
  "newMessage": {
    "role": "user",
    "parts": [{"text": "What is the capital of France?"}]
  }
}'

Run agent (streaming) 

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/api/run_sse -d '{
  "appName": "my_sample_agent",
  "userId": "u_123",
  "sessionId": "s_abc",
  "newMessage": {
    "role": "user",
    "parts": [{"text": "What is the weather in New York?"}]
  },
  "streaming": true
}'

Use deployed agents in the Google Cloud console

For deployed agents developed using Agent Development Kit (ADK), you can use the Google Cloud console to interact with your agent:

  1. In the Google Cloud console, go to the Agent Platform Deployments page.

    Go to Agent Platform Deployments

    Runtimes that are part of the selected project appear in the list. You can use the Filter field to filter the list by your specified column.

  2. Click the name of your runtime.

  3. Click the Playground tab.

  4. You can Type a message to interact with your agent, and click New Session to start a new session with your agent.

  5. If you enabled traces through OpenTelemetry, you can view details about your agent's behavior during your interactions:

    • Trace: Traces of your conversations with the agent.

    • Event: A graph of invoked APIs and event details during your conversations with the agent.

    • State: Information about your agent's state during your conversations.

    • Sessions: A list of sessions associated with your agent. For more information, see Manage using Google Cloud console or API calls

Playground support

You can use the following frameworks to try your agent:

Framework Chat with agent View sessions
Agent Development Kit (ADK) Supported Supported. Requires agent to implement Agent Platform Sessions for persistency.
Agent2Agent (A2A) Supported. Requires agent to implement Agent Platform Sessions for persistency. Supported. Requires agent to use Agent Platform Sessions, and the agent must send the user_id value as part of the context object. For an example on how to pass the user_id value as part of the agent executor, see the Get started with A2A notebook.

What's next