google / google/adk-js

Feature: Ergonomic TypeScript client for remote Vertex AI Agent Engine (parity with Python vertexai.agent_engines)

Open
#512 1 comment 1 reaction 2 assignees Claimed by @AmaadMartin View on GitHub
enhancement needs review
Dominant language
TypeScript
Stars
1.4k
Forks
205
Avg merge
3d 16h
Merged PRs (30d)
92

Description

## Summary

Python has an ergonomic remote client for a **deployed** Vertex AI Agent Engine:

```python
import vertexai

client = vertexai.Client(project="PROJECT_ID", location="LOCATION")
adk_app = client.agent_engines.get(
name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID"
)

session = await adk_app.async_create_session(
user_id="USER_ID",
session_id="SESSION_ID", # optional; user-provided IDs are useful for HITL apps
)

async for event in adk_app.async_stream_query(
user_id="USER_ID",
session_id=session["id"],
message="Hello",
):
print(event)
```

In TypeScript / Node.js there is no equivalent high-level API. NestJS (and other Node backends) that **consume** a Python-deployed Agent Engine must use the low-level `@google-cloud/aiplatform` `ReasoningEngineExecutionServiceClient` and manually call:

- `queryReasoningEngine({ classMethod: 'async_create_session', input: ... })`
- `streamQueryReasoningEngine({ classMethod: 'async_stream_query', input: ... })`

…including hand-rolling protobuf `Struct` encoding for `input`.

## Motivation

Many production stacks deploy agents with **Python ADK + Agent Engine**, but orchestrate WhatsApp / CRM / HITL from a **TypeScript** API. Today that TS side has:

| Capability | Python (`vertexai.agent_engines`) | TypeScript today |
|---|---|---|
| Get remote engine | `client.agent_engines.get(name)` | Build resource name string yourself |
| Create session | `await adk_app.async_create_session(...)` | `queryReasoningEngine` + `classMethod` |
| Stream query | `async for event in adk_app.async_stream_query(...)` | `streamQueryReasoningEngine` + SSE/chunk parsing |
| Typed input | Plain kwargs | Manual protobuf Struct (`fields` / `stringValue`) |

This friction causes brittle client code (session probe vs create, error wrapping, Struct encoding) and a large DX gap vs Python.

## Proposed API (sketch)

Something in `@google/adk` (or a companion package / `@google-cloud/aiplatform` helper) along the lines of:

```ts
import { AgentEngineClient } from '@google/adk'; // or vertex AI Node SDK

const engine = await AgentEngineClient.get({
project: 'PROJECT_ID',
location: 'LOCATION',
reasoningEngineId: 'RESOURCE_ID',
});

await engine.createSession({
userId: 'user_wa_123',
sessionId: 'conversation-uuid', // optional
});

for await (const event of engine.streamQuery({
userId: 'user_wa_123',
sessionId: 'conversation-uuid',
message: 'Hello',
})) {
console.log(event);
}
```

Ideally mirroring Python’s supported operations: `async_create_session`, `async_get_session`, `async_list_sessions`, `async_delete_session`, `async_stream_query` (and memory helpers if applicable).

## Related

- Python docs: [Use an ADK agent (Agent Platform)](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/use-an-adk-agent)
- Low-level Node client today: [`@google-cloud/aiplatform` `ReasoningEngineExecutionServiceClient`](https://github.com/googleapis/nodejs-aiplatform)
- Cross-link: this may also belong as a feature on [`googleapis/nodejs-aiplatform`](https://github.com/googleapis/nodejs-aiplatform) (where Python’s `vertexai.agent_engines` lives). Opening here because ADK TS is the natural community entry point for agent DX parity.

## Ask

Please consider adding (or documenting) an official ergonomic TypeScript remote client for deployed Agent Engines, with parity to Python `vertexai.Client().agent_engines`.

Happy to provide a minimal NestJS reproduction of the current low-level client if useful.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.