mirror of
https://github.com/googleapis/genai-toolbox.git
synced 2026-01-31 10:18:28 -05:00
Compare commits
7 Commits
migrate-go
...
docs-py-sd
| Author | SHA1 | Date | |
|---|---|---|---|
|
f5d8be166f | ||
|
|
2a68f8a36b | ||
|
|
f0c7eb129b | ||
|
|
fef07c71a1 | ||
|
|
9a232461b7 | ||
|
|
12b25a0beb | ||
|
|
073c8b3268 |
@@ -7,41 +7,6 @@ description: >
|
||||
---
|
||||
|
||||
|
||||
## Overview
|
||||
|
||||
|
||||
|
||||
# MCP Toolbox SDKs for Go
|
||||
|
||||
[](https://opensource.org/licenses/Apache-2.0)
|
||||
[](https://googleapis.github.io/genai-toolbox/)
|
||||
[](https://discord.gg/Dmm69peqjh)
|
||||
[](https://medium.com/@mcp_toolbox)
|
||||
[](https://goreportcard.com/report/github.com/googleapis/mcp-toolbox-sdk-go)
|
||||
[](https://img.shields.io/github/v/release/googleapis/mcp-toolbox-sdk-go)
|
||||
[](https://img.shields.io/github/go-mod/go-version/googleapis/mcp-toolbox-sdk-go)
|
||||
|
||||
This repository contains the Go SDK designed to seamlessly integrate the
|
||||
functionalities of the [MCP
|
||||
Toolbox](https://github.com/googleapis/genai-toolbox) into your Gen AI
|
||||
applications. The SDK allow you to load tools defined in Toolbox and use them
|
||||
as standard Go tools within popular orchestration frameworks
|
||||
or your custom code.
|
||||
|
||||
This simplifies the process of incorporating external functionalities (like
|
||||
Databases or APIs) managed by Toolbox into your GenAI applications.
|
||||
|
||||
<!-- TOC -->
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Which Package Should I Use?](#which-package-should-i-use)
|
||||
- [Available Packages](#available-packages)
|
||||
- [Getting Started](#getting-started)
|
||||
|
||||
<!-- /TOC -->
|
||||
|
||||
## Overview
|
||||
|
||||
The MCP Toolbox service provides a centralized way to manage and expose tools
|
||||
@@ -57,58 +22,4 @@ The Go SDK act as clients for that service. They handle the communication needed
|
||||
By using the SDK, you can easily leverage your Toolbox-managed tools directly
|
||||
within your Go applications or AI orchestration frameworks.
|
||||
|
||||
## Which Package Should I Use?
|
||||
|
||||
Choosing the right package depends on how you are building your application:
|
||||
|
||||
- [`core`](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/core):
|
||||
This is a framework agnostic way to connect the tools to popular frameworks
|
||||
like Google GenAI, LangChain, etc.
|
||||
|
||||
- [`tbadk`](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/tbadk):
|
||||
This package provides a way to connect tools to ADK Go.
|
||||
|
||||
- [`tbgenkit`](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/tbgenkit):
|
||||
This package provides a functionality to convert the Tool fetched using the core package
|
||||
into a Genkit Go compatible tool.
|
||||
|
||||
## Available Packages
|
||||
|
||||
This repository hosts the following Go packages. See the package-specific
|
||||
README for detailed installation and usage instructions:
|
||||
|
||||
| Package | Target Use Case | Integration | Path | Details (README) |
|
||||
| :------ | :----------| :---------- | :---------------------- | :---------- |
|
||||
| `core` | Framework-agnostic / Custom applications | Use directly / Custom | `core/` | 📄 [View README](https://github.com/googleapis/mcp-toolbox-sdk-go/blob/main/core/README.md) |
|
||||
| `tbadk` | ADK Go | Use directly | `tbadk/` | 📄 [View README](https://github.com/googleapis/mcp-toolbox-sdk-go/blob/main/tbadk/README.md) |
|
||||
| `tbgenkit` | Genkit Go | Along with core | `tbgenkit/` | 📄 [View README](https://github.com/googleapis/mcp-toolbox-sdk-go/blob/main/tbgenkit/README.md) |
|
||||
|
||||
## Getting Started
|
||||
|
||||
To get started using Toolbox tools with an application, follow these general steps:
|
||||
|
||||
1. **Set up and Run the Toolbox Service:**
|
||||
|
||||
Before using the SDKs, you need the MCP Toolbox server running. Follow
|
||||
the instructions here: [**Toolbox Getting Started
|
||||
Guide**](https://github.com/googleapis/genai-toolbox?tab=readme-ov-file#getting-started)
|
||||
|
||||
2. **Install the Appropriate SDK:**
|
||||
|
||||
Choose the package based on your needs (see "[Which Package Should I Use?](#which-package-should-i-use)" above)
|
||||
Use this command to install the SDK module
|
||||
|
||||
```bash
|
||||
# For the core, framework-agnostic SDK
|
||||
go get github.com/googleapis/mcp-toolbox-sdk-go
|
||||
```
|
||||
|
||||
3. **Use the SDK:**
|
||||
|
||||
Consult the README for your chosen package (linked in the "[Available
|
||||
Packages](#available-packages)" section above) for detailed instructions on
|
||||
how to connect the client, load tool definitions, invoke tools, configure
|
||||
authentication/binding, and integrate them into your application or
|
||||
framework.
|
||||
|
||||
[Github](https://github.com/googleapis/mcp-toolbox-sdk-go)
|
||||
@@ -1,148 +0,0 @@
|
||||
---
|
||||
title: "tbGenkit Package"
|
||||
linkTitle: "tbGenkit"
|
||||
type: docs
|
||||
weight: 1
|
||||
---
|
||||
|
||||
|
||||
|
||||
# MCP Toolbox TBGenkit Package
|
||||
|
||||
[](https://opensource.org/licenses/Apache-2.0)
|
||||
|
||||
This package allows you to seamlessly integrate the functionalities of
|
||||
[Toolbox](https://github.com/googleapis/genai-toolbox) allowing you to load and
|
||||
use tools defined in the service as standard Genkit Tools within your Genkit Go
|
||||
applications.
|
||||
|
||||
This simplifies integrating external functionalities (like APIs, databases, or
|
||||
custom logic) managed by the Toolbox into your workflows, especially those
|
||||
involving Large Language Models (LLMs).
|
||||
|
||||
|
||||
<!-- TOC ignore:true -->
|
||||
<!-- TOC -->
|
||||
|
||||
- [Installation](#installation)
|
||||
- [Quickstart](#quickstart)
|
||||
- [Convert Toolbox Tool to a Genkit Tool](#convert-toolbox-tool-to-a-genkit-tool)
|
||||
- [Contributing](#contributing)
|
||||
- [License](#license)
|
||||
- [Support](#support)
|
||||
- [Samples for Reference](#samples-for-reference)
|
||||
<!-- /TOC -->
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
go get github.com/googleapis/mcp-toolbox-sdk-go
|
||||
```
|
||||
This SDK is supported on Go version 1.24.4 and higher.
|
||||
|
||||
## Quickstart
|
||||
|
||||
For more information on how to load a ToolboxTool, see [the core package](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/core)
|
||||
|
||||
## Convert Toolbox Tool to a Genkit Tool
|
||||
|
||||
```go
|
||||
"github.com/googleapis/mcp-toolbox-sdk-go/tbgenkit"
|
||||
|
||||
func main() {
|
||||
// Assuming the toolbox tool is loaded
|
||||
// Make sure to add error checks for debugging
|
||||
ctx := context.Background()
|
||||
g, err := genkit.Init(ctx)
|
||||
|
||||
genkitTool, err := tbgenkit.ToGenkitTool(toolboxTool, g)
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
For end-to-end example on how to use Toolbox with Genkit Go, check out the [/samples/](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/tbgenkit/samples) folder
|
||||
|
||||
# Contributing
|
||||
|
||||
Contributions are welcome! Please refer to the [DEVELOPER.md](/DEVELOPER.md)
|
||||
file for guidelines on how to set up a development environment and run tests.
|
||||
|
||||
# License
|
||||
|
||||
This project is licensed under the Apache License 2.0. See the
|
||||
[LICENSE](https://github.com/googleapis/mcp-toolbox-sdk-go/blob/main/LICENSE) file for details.
|
||||
|
||||
# Support
|
||||
|
||||
If you encounter issues or have questions, check the existing [GitHub Issues](https://github.com/googleapis/genai-toolbox/issues) for the main Toolbox project.
|
||||
|
||||
# Samples for Reference
|
||||
|
||||
<details>
|
||||
<summary>Genkit Go</summary>
|
||||
|
||||
```go
|
||||
//This sample contains a complete example on how to integrate MCP Toolbox Go SDK with Genkit Go using the tbgenkit package.
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"log"
|
||||
|
||||
"github.com/googleapis/mcp-toolbox-sdk-go/core"
|
||||
"github.com/googleapis/mcp-toolbox-sdk-go/tbgenkit"
|
||||
|
||||
"github.com/firebase/genkit/go/ai"
|
||||
"github.com/firebase/genkit/go/genkit"
|
||||
"github.com/firebase/genkit/go/plugins/googlegenai"
|
||||
)
|
||||
|
||||
func main() {
|
||||
ctx := context.Background()
|
||||
toolboxClient, err := core.NewToolboxClient("http://127.0.0.1:5000")
|
||||
if err != nil {
|
||||
log.Fatalf("Failed to create Toolbox client: %v", err)
|
||||
}
|
||||
|
||||
// Load the tools using the MCP Toolbox SDK.
|
||||
tools, err := toolboxClient.LoadToolset("my-toolset", ctx)
|
||||
if err != nil {
|
||||
log.Fatalf("Failed to load tools: %v\nMake sure your Toolbox server is running and the tool is configured.", err)
|
||||
}
|
||||
|
||||
// Initialize genkit
|
||||
g := genkit.Init(ctx,
|
||||
genkit.WithPlugins(&googlegenai.GoogleAI{}),
|
||||
genkit.WithDefaultModel("googleai/gemini-1.5-flash"),
|
||||
)
|
||||
|
||||
// Convert your tool to a Genkit tool.
|
||||
genkitTools := make([]ai.Tool, len(tools))
|
||||
for i, tool := range tools {
|
||||
newTool, err := tbgenkit.ToGenkitTool(tool, g)
|
||||
if err != nil {
|
||||
log.Fatalf("Failed to convert tool: %v\n", err)
|
||||
}
|
||||
genkitTools[i] = newTool
|
||||
}
|
||||
|
||||
toolRefs := make([]ai.ToolRef, len(genkitTools))
|
||||
|
||||
for i, tool := range genkitTools {
|
||||
toolRefs[i] = tool
|
||||
}
|
||||
|
||||
// Generate llm response using prompts and tools.
|
||||
resp, err := genkit.Generate(ctx, g,
|
||||
ai.WithPrompt("Find hotels in Basel with Basel in it's name."),
|
||||
ai.WithTools(toolRefs...),
|
||||
)
|
||||
if err != nil {
|
||||
log.Fatalf("%v\n", err)
|
||||
}
|
||||
fmt.Println(resp.Text())
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
@@ -22,4 +22,36 @@ These Python SDKs act as clients for that service. They handle the communication
|
||||
By using these SDKs, you can easily leverage your Toolbox-managed tools directly
|
||||
within your Python applications or AI orchestration frameworks.
|
||||
|
||||
[Github](https://github.com/googleapis/mcp-toolbox-sdk-python)
|
||||
## Which Package Should I Use?
|
||||
|
||||
Choosing the right package depends on how you are building your application:
|
||||
|
||||
* [`toolbox-langchain`](langchain):
|
||||
Use this package if you are building your application using the LangChain or
|
||||
LangGraph frameworks. It provides tools that are directly compatible with the
|
||||
LangChain ecosystem (`BaseTool` interface), simplifying integration.
|
||||
* [`toolbox-llamaindex`](llamaindex):
|
||||
Use this package if you are building your application using the LlamaIndex framework.
|
||||
It provides tools that are directly compatible with the
|
||||
LlamaIndex ecosystem (`BaseTool` interface), simplifying integration.
|
||||
* [`toolbox-core`](core):
|
||||
Use this package if you are not using LangChain/LangGraph or any other
|
||||
orchestration framework, or if you need a framework-agnostic way to interact
|
||||
with Toolbox tools (e.g., for custom orchestration logic or direct use in
|
||||
Python scripts).
|
||||
|
||||
## Available Packages
|
||||
|
||||
This repository hosts the following Python packages. See the package-specific
|
||||
README for detailed installation and usage instructions:
|
||||
|
||||
| Package | Target Use Case | Integration | Path | Details (README) | PyPI Status |
|
||||
| :------ | :---------- | :---------- | :---------------------- | :---------- | :---------
|
||||
| `toolbox-core` | Framework-agnostic / Custom applications | Use directly / Custom | `packages/toolbox-core/` | 📄 [View README](https://github.com/googleapis/mcp-toolbox-sdk-python/blob/main/packages/toolbox-core/README.md) |  |
|
||||
| `toolbox-langchain` | LangChain / LangGraph applications | LangChain / LangGraph | `packages/toolbox-langchain/` | 📄 [View README](https://github.com/googleapis/mcp-toolbox-sdk-python/blob/main/packages/toolbox-langchain/README.md) |  |
|
||||
| `toolbox-llamaindex` | LlamaIndex applications | LlamaIndex | `packages/toolbox-llamaindex/` | 📄 [View README](https://github.com/googleapis/mcp-toolbox-sdk-python/blob/main/packages/toolbox-llamaindex/README.md) |  |
|
||||
|
||||
|
||||
{{< notice note >}}
|
||||
Source code for [python-sdk](https://github.com/googleapis/mcp-toolbox-sdk-python)
|
||||
{{< /notice >}}
|
||||
|
||||
401
docs/en/sdks/python-sdk/langchain/index.md
Normal file
401
docs/en/sdks/python-sdk/langchain/index.md
Normal file
@@ -0,0 +1,401 @@
|
||||
---
|
||||
title: "langchain"
|
||||
type: docs
|
||||
weight: 8
|
||||
description: >
|
||||
Toolbox-langchain SDK for connecting to the MCP Toolbox server and invoking tools programmatically.
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The `toolbox-langchain` package provides a Python interface to the MCP Toolbox service, enabling you to load and invoke tools from your own applications.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
pip install toolbox-langchain
|
||||
```
|
||||
## Quickstart
|
||||
|
||||
Here's a minimal example to get you started using
|
||||
[LangGraph](https://langchain-ai.github.io/langgraph/reference/prebuilt/#langgraph.prebuilt.chat_agent_executor.create_react_agent):
|
||||
|
||||
```py
|
||||
from toolbox_langchain import ToolboxClient
|
||||
from langchain_google_vertexai import ChatVertexAI
|
||||
from langgraph.prebuilt import create_react_agent
|
||||
|
||||
async with ToolboxClient("http://127.0.0.1:5000") as toolbox:
|
||||
tools = toolbox.load_toolset()
|
||||
|
||||
model = ChatVertexAI(model="gemini-2.0-flash-001")
|
||||
agent = create_react_agent(model, tools)
|
||||
|
||||
prompt = "How's the weather today?"
|
||||
|
||||
for s in agent.stream({"messages": [("user", prompt)]}, stream_mode="values"):
|
||||
message = s["messages"][-1]
|
||||
if isinstance(message, tuple):
|
||||
print(message)
|
||||
else:
|
||||
message.pretty_print()
|
||||
```
|
||||
{{< notice tip >}}
|
||||
For a complete, end-to-end example including setting up the service and using an SDK, see the full tutorial: [Toolbox Quickstart Tutorial](getting-started/local_quickstart)
|
||||
{{< /notice >}}
|
||||
|
||||
## Usage
|
||||
|
||||
Import and initialize the toolbox client.
|
||||
|
||||
```py
|
||||
from toolbox_langchain import ToolboxClient
|
||||
|
||||
# Replace with your Toolbox service's URL
|
||||
async with ToolboxClient("http://127.0.0.1:5000") as toolbox:
|
||||
```
|
||||
|
||||
## Loading Tools
|
||||
|
||||
### Load a toolset
|
||||
|
||||
A toolset is a collection of related tools. You can load all tools in a toolset
|
||||
or a specific one:
|
||||
|
||||
```py
|
||||
# Load all tools
|
||||
tools = toolbox.load_toolset()
|
||||
|
||||
# Load a specific toolset
|
||||
tools = toolbox.load_toolset("my-toolset")
|
||||
```
|
||||
|
||||
### Load a single tool
|
||||
|
||||
```py
|
||||
tool = toolbox.load_tool("my-tool")
|
||||
```
|
||||
|
||||
Loading individual tools gives you finer-grained control over which tools are
|
||||
available to your LLM agent.
|
||||
|
||||
## Use with LangChain
|
||||
|
||||
LangChain's agents can dynamically choose and execute tools based on the user
|
||||
input. Include tools loaded from the Toolbox SDK in the agent's toolkit:
|
||||
|
||||
```py
|
||||
from langchain_google_vertexai import ChatVertexAI
|
||||
|
||||
model = ChatVertexAI(model="gemini-2.0-flash-001")
|
||||
|
||||
# Initialize agent with tools
|
||||
agent = model.bind_tools(tools)
|
||||
|
||||
# Run the agent
|
||||
result = agent.invoke("Do something with the tools")
|
||||
```
|
||||
|
||||
## Use with LangGraph
|
||||
|
||||
Integrate the Toolbox SDK with LangGraph to use Toolbox service tools within a
|
||||
graph-based workflow. Follow the [official
|
||||
guide](https://langchain-ai.github.io/langgraph/) with minimal changes.
|
||||
|
||||
### Represent Tools as Nodes
|
||||
|
||||
Represent each tool as a LangGraph node, encapsulating the tool's execution within the node's functionality:
|
||||
|
||||
```py
|
||||
from toolbox_langchain import ToolboxClient
|
||||
from langgraph.graph import StateGraph, MessagesState
|
||||
from langgraph.prebuilt import ToolNode
|
||||
|
||||
# Define the function that calls the model
|
||||
def call_model(state: MessagesState):
|
||||
messages = state['messages']
|
||||
response = model.invoke(messages)
|
||||
return {"messages": [response]} # Return a list to add to existing messages
|
||||
|
||||
model = ChatVertexAI(model="gemini-2.0-flash-001")
|
||||
builder = StateGraph(MessagesState)
|
||||
tool_node = ToolNode(tools)
|
||||
|
||||
builder.add_node("agent", call_model)
|
||||
builder.add_node("tools", tool_node)
|
||||
```
|
||||
|
||||
### Connect Tools with LLM
|
||||
|
||||
Connect tool nodes with LLM nodes. The LLM decides which tool to use based on
|
||||
input or context. Tool output can be fed back into the LLM:
|
||||
|
||||
```py
|
||||
from typing import Literal
|
||||
from langgraph.graph import END, START
|
||||
from langchain_core.messages import HumanMessage
|
||||
|
||||
# Define the function that determines whether to continue or not
|
||||
def should_continue(state: MessagesState) -> Literal["tools", END]:
|
||||
messages = state['messages']
|
||||
last_message = messages[-1]
|
||||
if last_message.tool_calls:
|
||||
return "tools" # Route to "tools" node if LLM makes a tool call
|
||||
return END # Otherwise, stop
|
||||
|
||||
builder.add_edge(START, "agent")
|
||||
builder.add_conditional_edges("agent", should_continue)
|
||||
builder.add_edge("tools", 'agent')
|
||||
|
||||
graph = builder.compile()
|
||||
|
||||
graph.invoke({"messages": [HumanMessage(content="Do something with the tools")]})
|
||||
```
|
||||
|
||||
## Manual usage
|
||||
|
||||
Execute a tool manually using the `invoke` method:
|
||||
|
||||
```py
|
||||
result = tools[0].invoke({"name": "Alice", "age": 30})
|
||||
```
|
||||
|
||||
This is useful for testing tools or when you need precise control over tool
|
||||
execution outside of an agent framework.
|
||||
|
||||
## Client to Server Authentication
|
||||
|
||||
This section describes how to authenticate the ToolboxClient itself when
|
||||
connecting to a Toolbox server instance that requires authentication. This is
|
||||
crucial for securing your Toolbox server endpoint, especially when deployed on
|
||||
platforms like Cloud Run, GKE, or any environment where unauthenticated access
|
||||
is restricted.
|
||||
|
||||
This client-to-server authentication ensures that the Toolbox server can verify
|
||||
the identity of the client making the request before any tool is loaded or
|
||||
called. It is different from [Authenticating Tools](#authenticating-tools),
|
||||
which deals with providing credentials for specific tools within an already
|
||||
connected Toolbox session.
|
||||
|
||||
### When is Client-to-Server Authentication Needed?
|
||||
|
||||
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.
|
||||
- You have custom authentication middleware on your self-hosted Toolbox server.
|
||||
|
||||
Without proper client authentication in these scenarios, attempts to connect or
|
||||
make calls (like `load_tool`) will likely fail with `Unauthorized` errors.
|
||||
|
||||
### How it works
|
||||
|
||||
The `ToolboxClient` allows you to specify functions (or coroutines for the async
|
||||
client) that dynamically generate HTTP headers for every request sent to the
|
||||
Toolbox server. The most common use case is to add an Authorization header 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.
|
||||
|
||||
### Configuration
|
||||
|
||||
You can configure these dynamic headers as follows:
|
||||
|
||||
```python
|
||||
from toolbox_langchain import ToolboxClient
|
||||
|
||||
async with ToolboxClient(
|
||||
"toolbox-url",
|
||||
client_headers={"header1": header1_getter, "header2": header2_getter, ...}
|
||||
) as client:
|
||||
```
|
||||
|
||||
### Authenticating with Google Cloud Servers
|
||||
|
||||
For Toolbox servers hosted on Google Cloud (e.g., Cloud Run) and requiring
|
||||
`Google ID token` authentication, the helper module
|
||||
[auth_methods](https://github.com/googleapis/mcp-toolbox-sdk-python/blob/main/packages/toolbox-core/src/toolbox_core/auth_methods.py) provides utility functions.
|
||||
|
||||
### Step by Step Guide for Cloud Run
|
||||
|
||||
1. **Configure Permissions**:
|
||||
[Grant](https://cloud.google.com/run/docs/securing/managing-access#service-add-principals)
|
||||
the `roles/run.invoker` IAM role on the Cloud
|
||||
Run service to the principal. This could be your `user account email` or a
|
||||
`service account`.
|
||||
2. **Configure Credentials**
|
||||
- Local Development: Set up
|
||||
[ADC](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment).
|
||||
- Google Cloud Environments: When running within Google Cloud (e.g., Compute
|
||||
Engine, GKE, another Cloud Run service, Cloud Functions), ADC is typically
|
||||
configured automatically, using the environment's default service account.
|
||||
3. **Connect to the Toolbox Server**
|
||||
|
||||
```python
|
||||
from toolbox_langchain import ToolboxClient
|
||||
from toolbox_core import auth_methods
|
||||
|
||||
auth_token_provider = auth_methods.aget_google_id_token(URL) # can also use sync method
|
||||
async with ToolboxClient(
|
||||
URL,
|
||||
client_headers={"Authorization": auth_token_provider},
|
||||
) as client:
|
||||
tools = client.load_toolset()
|
||||
|
||||
# Now, you can use the client as usual.
|
||||
```
|
||||
|
||||
|
||||
## Authenticating Tools
|
||||
|
||||
{{< notice info >}}
|
||||
Always use HTTPS to connect your application with the Toolbox service, especially when using tools with authentication configured. Using HTTP exposes your application to serious security risks.
|
||||
{{< /notice >}}
|
||||
|
||||
Some tools require user authentication to access sensitive data.
|
||||
|
||||
### Supported Authentication Mechanisms
|
||||
Toolbox currently supports authentication using the [OIDC
|
||||
protocol](https://openid.net/specs/openid-connect-core-1_0.html) with [ID
|
||||
tokens](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) (not
|
||||
access tokens) for [Google OAuth
|
||||
2.0](https://cloud.google.com/apigee/docs/api-platform/security/oauth/oauth-home).
|
||||
|
||||
### Configure Tools
|
||||
|
||||
Refer to [these
|
||||
instructions](https://googleapis.github.io/genai-toolbox/resources/tools/#authenticated-parameters) on
|
||||
configuring tools for authenticated parameters.
|
||||
|
||||
### Configure SDK
|
||||
|
||||
You need a method to retrieve an ID token from your authentication service:
|
||||
|
||||
```py
|
||||
async def get_auth_token():
|
||||
# ... Logic to retrieve ID token (e.g., from local storage, OAuth flow)
|
||||
# This example just returns a placeholder. Replace with your actual token retrieval.
|
||||
return "YOUR_ID_TOKEN" # Placeholder
|
||||
```
|
||||
|
||||
#### Add Authentication to a Tool
|
||||
|
||||
```py
|
||||
async with ToolboxClient("http://127.0.0.1:5000") as toolbox:
|
||||
tools = toolbox.load_toolset()
|
||||
|
||||
auth_tool = tools[0].add_auth_token_getter("my_auth", get_auth_token) # Single token
|
||||
|
||||
multi_auth_tool = tools[0].add_auth_token_getters({"auth_1": get_auth_1}, {"auth_2": get_auth_2}) # Multiple tokens
|
||||
|
||||
# OR
|
||||
|
||||
auth_tools = [tool.add_auth_token_getter("my_auth", get_auth_token) for tool in tools]
|
||||
```
|
||||
|
||||
#### Add Authentication While Loading
|
||||
|
||||
```py
|
||||
auth_tool = toolbox.load_tool(auth_token_getters={"my_auth": get_auth_token})
|
||||
|
||||
auth_tools = toolbox.load_toolset(auth_token_getters={"my_auth": get_auth_token})
|
||||
```
|
||||
{{< notice note >}}
|
||||
Adding auth tokens during loading only affect the tools loaded within that call.
|
||||
{{< /notice >}}
|
||||
|
||||
### Complete Example
|
||||
|
||||
```py
|
||||
import asyncio
|
||||
from toolbox_langchain import ToolboxClient
|
||||
|
||||
async def get_auth_token():
|
||||
# ... Logic to retrieve ID token (e.g., from local storage, OAuth flow)
|
||||
# This example just returns a placeholder. Replace with your actual token retrieval.
|
||||
return "YOUR_ID_TOKEN" # Placeholder
|
||||
|
||||
async with ToolboxClient("http://127.0.0.1:5000") as toolbox:
|
||||
tool = toolbox.load_tool("my-tool")
|
||||
|
||||
auth_tool = tool.add_auth_token_getter("my_auth", get_auth_token)
|
||||
result = auth_tool.invoke({"input": "some input"})
|
||||
print(result)
|
||||
```
|
||||
|
||||
## Binding Parameter Values
|
||||
|
||||
Predetermine values for tool parameters using the SDK. These values won't be
|
||||
modified by the LLM. This is useful for:
|
||||
|
||||
* **Protecting sensitive information:** API keys, secrets, etc.
|
||||
* **Enforcing consistency:** Ensuring specific values for certain parameters.
|
||||
* **Pre-filling known data:** Providing defaults or context.
|
||||
|
||||
### Binding Parameters to a Tool
|
||||
|
||||
```py
|
||||
async with ToolboxClient("http://127.0.0.1:5000") as toolbox:
|
||||
tools = toolbox.load_toolset()
|
||||
|
||||
bound_tool = tool[0].bind_param("param", "value") # Single param
|
||||
|
||||
multi_bound_tool = tools[0].bind_params({"param1": "value1", "param2": "value2"}) # Multiple params
|
||||
|
||||
# OR
|
||||
|
||||
bound_tools = [tool.bind_param("param", "value") for tool in tools]
|
||||
```
|
||||
|
||||
### Binding Parameters While Loading
|
||||
|
||||
```py
|
||||
bound_tool = toolbox.load_tool("my-tool", bound_params={"param": "value"})
|
||||
|
||||
bound_tools = toolbox.load_toolset(bound_params={"param": "value"})
|
||||
```
|
||||
{{< notice note >}}
|
||||
Bound values during loading only affect the tools loaded in that call.
|
||||
{{< /notice >}}
|
||||
|
||||
### Binding Dynamic Values
|
||||
|
||||
Use a function to bind dynamic values:
|
||||
|
||||
```py
|
||||
def get_dynamic_value():
|
||||
# Logic to determine the value
|
||||
return "dynamic_value"
|
||||
|
||||
dynamic_bound_tool = tool.bind_param("param", get_dynamic_value)
|
||||
```
|
||||
{{< notice note >}}
|
||||
You don’t need to modify tool configurations to bind parameter values.
|
||||
{{< /notice >}}
|
||||
|
||||
## Asynchronous Usage
|
||||
|
||||
For better performance through [cooperative
|
||||
multitasking](https://en.wikipedia.org/wiki/Cooperative_multitasking), you can
|
||||
use the asynchronous interfaces of the `ToolboxClient`.
|
||||
|
||||
{{< notice note >}}
|
||||
Asynchronous interfaces like `aload_tool` and `aload_toolset` require an asynchronous environment. For guidance on running asynchronous Python programs, see [asyncio documentation](https://docs.python.org/3/library/asyncio-runner.html#running-an-asyncio-program).
|
||||
{{< /notice >}}
|
||||
|
||||
```py
|
||||
import asyncio
|
||||
from toolbox_langchain import ToolboxClient
|
||||
|
||||
async def main():
|
||||
async with ToolboxClient("http://127.0.0.1:5000") as toolbox:
|
||||
tool = await client.aload_tool("my-tool")
|
||||
tools = await client.aload_toolset()
|
||||
response = await tool.ainvoke()
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
```
|
||||
Reference in New Issue
Block a user