mirror of
https://github.com/googleapis/genai-toolbox.git
synced 2026-02-03 03:35:02 -05:00
Compare commits
2 Commits
docs-js-sd
...
docs-js-sd
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
be4cf94abc | ||
|
|
61262a83e1 |
@@ -1,14 +1,14 @@
|
||||
---
|
||||
title: "Core"
|
||||
title: "Adk"
|
||||
type: docs
|
||||
weight: 8
|
||||
description: >
|
||||
MCP Toolbox Core SDK for integrating functionalities of MCP Toolbox into your Agentic apps.
|
||||
MCP Toolbox ADK SDK for integrating functionalities of MCP Toolbox into your apps.
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The `@toolbox-sdk/core` package provides a Javascript interface to the MCP Toolbox service, enabling you to load and invoke tools from your own applications.
|
||||
The `@toolbox-sdk/adk` package provides a Javascript interface to the MCP Toolbox service, enabling you to load and invoke tools from your own applications.
|
||||
|
||||
## Supported Environments
|
||||
|
||||
@@ -21,7 +21,7 @@ This SDK is a standard Node.js package built with TypeScript, ensuring broad com
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
npm install @toolbox-sdk/core
|
||||
npm install @toolbox-sdk/adk
|
||||
```
|
||||
|
||||
## Quickstart
|
||||
@@ -36,7 +36,7 @@ Here's a minimal example to get you started. Ensure your Toolbox service is runn
|
||||
|
||||
```javascript
|
||||
|
||||
import { ToolboxClient } from '@toolbox-sdk/core';
|
||||
import { ToolboxClient } from '@toolbox-sdk/adk';
|
||||
const client = new ToolboxClient(URL);
|
||||
|
||||
async function quickstart() {
|
||||
@@ -51,7 +51,7 @@ quickstart();
|
||||
```
|
||||
|
||||
{{< notice note>}}
|
||||
This guide uses modern ES Module (`import`) syntax. If your project uses CommonJS, you can import the library using require: `const { ToolboxClient } = require('@toolbox-sdk/core')`;.
|
||||
This guide uses modern ES Module (`import`) syntax. If your project uses CommonJS, you can import the library using require: `const { ToolboxClient } = require('@toolbox-sdk/adk')`;.
|
||||
{{< /notice >}}
|
||||
|
||||
## Usage
|
||||
@@ -59,7 +59,7 @@ quickstart();
|
||||
Import and initialize a Toolbox client, pointing it to the URL of your running Toolbox service.
|
||||
|
||||
```javascript
|
||||
import { ToolboxClient } from '@toolbox-sdk/core';
|
||||
import { ToolboxClient } from '@toolbox-sdk/adk';
|
||||
|
||||
// Replace with the actual URL where your Toolbox service is running
|
||||
const URL = 'http://127.0.0.1:5000';
|
||||
@@ -98,7 +98,7 @@ The SDK supports multiple transport protocols to communicate with the Toolbox se
|
||||
You can explicitly set the protocol by passing the `protocol` argument to the `ToolboxClient` constructor.
|
||||
|
||||
```javascript
|
||||
import { ToolboxClient, Protocol } from '@toolbox-sdk/core';
|
||||
import { ToolboxClient, Protocol } from '@toolbox-sdk/adk';
|
||||
|
||||
const URL = 'http://127.0.0.1:5000';
|
||||
|
||||
@@ -164,7 +164,8 @@ You'll need this type of authentication if your Toolbox server is configured to
|
||||
deny unauthenticated requests. For example:
|
||||
|
||||
- Your Toolbox server is deployed on Cloud Run and configured to "Require authentication."
|
||||
- Your server is behind an Identity-Aware Proxy (IAP) or a similar authentication layer.
|
||||
- Your server is behind an Identity-Aware Proxy (IAP) or a similar
|
||||
authentication layer.
|
||||
- You have custom authentication middleware on your self-hosted Toolbox server.
|
||||
|
||||
Without proper client authentication in these scenarios, attempts to connect or
|
||||
@@ -178,7 +179,8 @@ case is to add an [Authorization
|
||||
header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Authorization)
|
||||
with a bearer token (e.g., a Google ID token).
|
||||
|
||||
These header-generating functions are called just before each request, ensuring that fresh credentials or header values can be used.
|
||||
These header-generating functions are called just before each request, ensuring
|
||||
that fresh credentials or header values can be used.
|
||||
|
||||
### Configuration
|
||||
|
||||
@@ -324,7 +326,7 @@ Adding auth tokens during loading only affect the tools loaded within that call.
|
||||
### Complete Authentication Example
|
||||
|
||||
```javascript
|
||||
import { ToolboxClient } from '@toolbox-sdk/core';
|
||||
import { ToolboxClient } from '@toolbox-sdk/adk';
|
||||
|
||||
async function getAuthToken() {
|
||||
// ... Logic to retrieve ID token (e.g., from local storage, OAuth flow)
|
||||
@@ -336,7 +338,7 @@ const URL = 'http://127.0.0.1:5000';
|
||||
let client = new ToolboxClient(URL);
|
||||
const tool = await client.loadTool("my-tool");
|
||||
const authTool = tool.addAuthTokenGetters({"my_auth": getAuthToken});
|
||||
const result = await authTool({input:"some input"});
|
||||
const result = await authTool.runAsync(args: {input:"some input"});
|
||||
console.log(result);
|
||||
```
|
||||
|
||||
@@ -357,7 +359,8 @@ The parameter names used for binding (e.g., `"api_key"`) must exactly match the
|
||||
{{< /notice >}}
|
||||
|
||||
{{< notice note>}}
|
||||
You do not need to modify the tool's configuration in the Toolbox service to bind parameter values using the SDK.
|
||||
You do not need to modify the tool's configuration in the Toolbox service to
|
||||
> bind parameter values using the SDK.
|
||||
{{< /notice >}}
|
||||
|
||||
### Option A: Binding Parameters to a Loaded Tool
|
||||
@@ -367,7 +370,7 @@ specific tool instance.
|
||||
|
||||
```javascript
|
||||
|
||||
import { ToolboxClient } from '@toolbox-sdk/core';
|
||||
import { ToolboxClient } from '@toolbox-sdk/adk';
|
||||
|
||||
const URL = 'http://127.0.0.1:5000';
|
||||
let client = new ToolboxClient(URL);
|
||||
@@ -403,7 +406,6 @@ Instead of a static value, you can bind a parameter to a synchronous or
|
||||
asynchronous function. This function will be called *each time* the tool is
|
||||
invoked to dynamically determine the parameter's value at runtime.
|
||||
|
||||
|
||||
```javascript
|
||||
|
||||
async function getDynamicValue() {
|
||||
@@ -418,98 +420,53 @@ const dynamicBoundTool = tool.bindParam("param", getDynamicValue)
|
||||
You don't need to modify tool configurations to bind parameter values.
|
||||
{{< /notice >}}
|
||||
|
||||
# Using with Orchestration Frameworks
|
||||
# Using with ADK
|
||||
|
||||
<details open>
|
||||
|
||||
<summary>Langchain</summary>
|
||||
|
||||
[LangchainJS](https://js.langchain.com/docs/introduction/)
|
||||
ADK JS:
|
||||
|
||||
```javascript
|
||||
import {ToolboxClient} from "@toolbox-sdk/core"
|
||||
import { tool } from "@langchain/core/tools";
|
||||
import {FunctionTool, InMemoryRunner, LlmAgent} from '@google/adk';
|
||||
import {Content} from '@google/genai';
|
||||
import {ToolboxClient} from '@toolbox-sdk/core'
|
||||
|
||||
let client = ToolboxClient(URL)
|
||||
multiplyTool = await client.loadTool("multiply")
|
||||
const toolboxClient = new ToolboxClient("http://127.0.0.1:5000");
|
||||
const loadedTools = await toolboxClient.loadToolset();
|
||||
|
||||
const multiplyNumbers = tool(multiplyTool, {
|
||||
name: multiplyTool.getName(),
|
||||
description: multiplyTool.getDescription(),
|
||||
schema: multiplyTool.getParamSchema()
|
||||
export const rootAgent = new LlmAgent({
|
||||
name: 'weather_time_agent',
|
||||
model: 'gemini-2.5-flash',
|
||||
description:
|
||||
'Agent to answer questions about the time and weather in a city.',
|
||||
instruction:
|
||||
'You are a helpful agent who can answer user questions about the time and weather in a city.',
|
||||
tools: loadedTools,
|
||||
});
|
||||
|
||||
await multiplyNumbers.invoke({ a: 2, b: 3 });
|
||||
async function main() {
|
||||
const userId = 'test_user';
|
||||
const appName = rootAgent.name;
|
||||
const runner = new InMemoryRunner({agent: rootAgent, appName});
|
||||
const session = await runner.sessionService.createSession({
|
||||
appName,
|
||||
userId,
|
||||
});
|
||||
|
||||
const prompt = 'What is the weather in New York? And the time?';
|
||||
const content: Content = {
|
||||
role: 'user',
|
||||
parts: [{text: prompt}],
|
||||
};
|
||||
console.log(content);
|
||||
for await (const e of runner.runAsync({
|
||||
userId,
|
||||
sessionId: session.id,
|
||||
newMessage: content,
|
||||
})) {
|
||||
if (e.content?.parts?.[0]?.text) {
|
||||
console.log(`${e.author}: ${JSON.stringify(e.content, null, 2)}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
main().catch(console.error);
|
||||
```
|
||||
|
||||
The `multiplyNumbers` tool is compatible with [Langchain/Langraph
|
||||
agents](http://js.langchain.com/docs/concepts/agents/)
|
||||
such as [React
|
||||
Agents](https://langchain-ai.github.io/langgraphjs/reference/functions/langgraph_prebuilt.createReactAgent.html).
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
|
||||
<summary>LlamaIndex</summary>
|
||||
|
||||
[LlamaindexTS](https://ts.llamaindex.ai/)
|
||||
|
||||
```javascript
|
||||
import {ToolboxClient} from "@toolbox-sdk/core"
|
||||
import { tool } from "llamaindex";
|
||||
|
||||
let client = ToolboxClient(URL)
|
||||
multiplyTool = await client.loadTool("multiply")
|
||||
|
||||
const multiplyNumbers = tool({
|
||||
name: multiplyTool.getName(),
|
||||
description: multiplyTool.getDescription(),
|
||||
parameters: multiplyTool.getParamSchema(),
|
||||
execute: mutliplyTool
|
||||
});
|
||||
|
||||
await multiplyNumbers.call({ a: 2, b: 3 });
|
||||
```
|
||||
|
||||
The `multiplyNumbers` tool is compatible with LlamaIndex
|
||||
[agents](https://ts.llamaindex.ai/docs/llamaindex/migration/deprecated/agent)
|
||||
and [agent
|
||||
workflows](https://ts.llamaindex.ai/docs/llamaindex/modules/agents/agent_workflow).
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
|
||||
<summary>Genkit</summary>
|
||||
|
||||
[GenkitJS](https://genkit.dev/docs/get-started/#_top)
|
||||
```javascript
|
||||
import {ToolboxClient} from "@toolbox-sdk/core"
|
||||
import { genkit, z } from 'genkit';
|
||||
import { googleAI } from '@genkit-ai/googleai';
|
||||
|
||||
|
||||
let client = ToolboxClient(URL)
|
||||
multiplyTool = await client.loadTool("multiply")
|
||||
|
||||
const ai = genkit({
|
||||
plugins: [googleAI()],
|
||||
model: googleAI.model('gemini-1.5-pro'),
|
||||
});
|
||||
|
||||
const multiplyNumbers = ai.defineTool({
|
||||
name: multiplyTool.getName(),
|
||||
description: multiplyTool.getDescription(),
|
||||
inputSchema: multiplyTool.getParamSchema(),
|
||||
},
|
||||
multiplyTool,
|
||||
);
|
||||
|
||||
await ai.generate({
|
||||
prompt: 'Can you multiply 5 and 7?',
|
||||
tools: [multiplyNumbers],
|
||||
});
|
||||
```
|
||||
|
||||
</details>
|
||||
Reference in New Issue
Block a user