Skip to content
This repository was archived by the owner on Jul 16, 2025. It is now read-only.

Commit 489454b

Browse files
OskarStarkOskarStark
committed
docs: Add comprehensive documentation for Google Gemini server tools
- Created detailed documentation explaining URL Context, Google Search, and Code Execution tools - Added usage examples, configuration options, and best practices - Updated README.md to reference the new documentation - Covers implementation from PR #356
1 parent 58186ba commit 489454b

File tree

2 files changed

+230
-0
lines changed

2 files changed

+230
-0
lines changed

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -172,6 +172,10 @@ $response = $chain->call($messages, [
172172
To integrate LLMs with your application, LLM Chain supports [tool calling](https://platform.openai.com/docs/guides/function-calling) out of the box.
173173
Tools are services that can be called by the LLM to provide additional features or process data.
174174

175+
#### Server Tools (Google Gemini)
176+
177+
Google Gemini provides built-in server-side tools for enhanced capabilities without custom implementations. See the [Server Tools Documentation](docs/google-server-tools.md) for detailed usage instructions.
178+
175179
Tool calling can be enabled by registering the processors in the chain:
176180

177181
```php

‎docs/google-server-tools.md‎

Lines changed: 226 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
# Google Gemini Server Tools
2+
3+
Server tools are built-in capabilities provided by Google Gemini that allow the model to perform specific actions without requiring custom tool implementations. These tools run on Google's servers and provide access to external data and execution environments.
4+
5+
## Overview
6+
7+
Google Gemini provides several server-side tools that can be enabled when calling the model:
8+
9+
- **URL Context** - Fetches and analyzes content from URLs
10+
- **Google Search** - Performs web searches using Google
11+
- **Code Execution** - Executes code in a sandboxed environment
12+
13+
## Installation
14+
15+
Server tools are available through the Google platform bridge:
16+
17+
```php
18+
composer require php-llm/llm-chain
19+
```
20+
21+
## Basic Usage
22+
23+
To use server tools, specify them in the model options when creating a Gemini instance:
24+
25+
```php
26+
use PhpLlm\LlmChain\Platform\Bridge\Google\Gemini;
27+
use PhpLlm\LlmChain\Platform\Bridge\Google\PlatformFactory;
28+
29+
$platform = PlatformFactory::create($_ENV['GOOGLE_API_KEY']);
30+
31+
// Enable URL Context tool
32+
$llm = new Gemini('gemini-2.5-pro-preview-03-25', [
33+
'server_tools' => [
34+
'url_context' => true
35+
],
36+
'temperature' => 1.0
37+
]);
38+
```
39+
40+
## Available Server Tools
41+
42+
### URL Context
43+
44+
The URL Context tool allows Gemini to fetch and analyze content from web pages. This is useful for:
45+
46+
- Analyzing current web content
47+
- Extracting information from specific pages
48+
- Understanding context from external sources
49+
50+
```php
51+
$llm = new Gemini('gemini-2.5-pro-preview-03-25', [
52+
'server_tools' => [
53+
'url_context' => true
54+
]
55+
]);
56+
57+
$messages = new MessageBag(
58+
Message::ofUser('What was the 12 month Euribor rate a week ago based on https://www.euribor-rates.eu/en/current-euribor-rates/4/euribor-rate-12-months/')
59+
);
60+
61+
$response = $chain->call($messages);
62+
```
63+
64+
### Google Search
65+
66+
The Google Search tool enables the model to search the web and incorporate search results into its responses:
67+
68+
```php
69+
$llm = new Gemini('gemini-2.5-pro-preview-03-25', [
70+
'server_tools' => [
71+
'google_search' => true
72+
]
73+
]);
74+
75+
$messages = new MessageBag(
76+
Message::ofUser('What are the latest developments in quantum computing?')
77+
);
78+
79+
$response = $chain->call($messages);
80+
```
81+
82+
### Code Execution
83+
84+
The Code Execution tool provides a sandboxed environment for running code:
85+
86+
```php
87+
$llm = new Gemini('gemini-2.5-pro-preview-03-25', [
88+
'server_tools' => [
89+
'code_execution' => true
90+
]
91+
]);
92+
93+
$messages = new MessageBag(
94+
Message::ofUser('Calculate the factorial of 20 and show me the code')
95+
);
96+
97+
$response = $chain->call($messages);
98+
```
99+
100+
## Using Multiple Server Tools
101+
102+
You can enable multiple server tools simultaneously:
103+
104+
```php
105+
$llm = new Gemini('gemini-2.5-pro-preview-03-25', [
106+
'server_tools' => [
107+
'url_context' => true,
108+
'google_search' => true,
109+
'code_execution' => true
110+
]
111+
]);
112+
```
113+
114+
## Advanced Configuration
115+
116+
### Server Tools with Parameters
117+
118+
For server tools that accept parameters, you can pass an array instead of `true`:
119+
120+
```php
121+
$llm = new Gemini('gemini-2.5-pro-preview-03-25', [
122+
'server_tools' => [
123+
'url_context' => [
124+
// Future parameters can be added here
125+
]
126+
]
127+
]);
128+
```
129+
130+
### Combining with Custom Tools
131+
132+
Server tools can be used alongside custom tools from the toolbox:
133+
134+
```php
135+
use PhpLlm\LlmChain\Chain\Toolbox\Tool\Clock;
136+
use PhpLlm\LlmChain\Chain\Toolbox\Toolbox;
137+
138+
$toolbox = Toolbox::create(new Clock());
139+
$processor = new ChainProcessor($toolbox);
140+
$chain = new Chain($platform, $llm);
141+
142+
$llm = new Gemini('gemini-2.5-pro-preview-03-25', [
143+
'server_tools' => [
144+
'url_context' => true
145+
]
146+
]);
147+
148+
// Both server tools and custom tools will be available
149+
```
150+
151+
## Implementation Details
152+
153+
The server tools implementation works by:
154+
155+
1. Converting server tool configurations into the format expected by Google's API
156+
2. For boolean `true` values, an empty `ArrayObject` is sent as required by the API
157+
3. Server tools are added to the `tools` array in the API request
158+
4. The `server_tools` option is separate from regular `tools` to prevent toolbox tools from being overwritten
159+
160+
## Best Practices
161+
162+
1. **Enable only needed tools** - Each enabled tool increases latency and token usage
163+
2. **Consider rate limits** - Server tools may have usage limits
164+
3. **Combine wisely** - Use server tools for external data and custom tools for application logic
165+
4. **Handle failures gracefully** - Server tools may fail due to network issues or API limits
166+
167+
## Complete Example
168+
169+
```php
170+
<?php
171+
172+
use PhpLlm\LlmChain\Chain\Chain;
173+
use PhpLlm\LlmChain\Chain\Toolbox\ChainProcessor;
174+
use PhpLlm\LlmChain\Chain\Toolbox\Tool\Clock;
175+
use PhpLlm\LlmChain\Chain\Toolbox\Toolbox;
176+
use PhpLlm\LlmChain\Platform\Bridge\Google\Gemini;
177+
use PhpLlm\LlmChain\Platform\Bridge\Google\PlatformFactory;
178+
use PhpLlm\LlmChain\Platform\Message\Message;
179+
use PhpLlm\LlmChain\Platform\Message\MessageBag;
180+
181+
// Initialize platform
182+
$platform = PlatformFactory::create($_ENV['GOOGLE_API_KEY']);
183+
184+
// Configure model with server tools
185+
$llm = new Gemini('gemini-2.5-pro-preview-03-25', [
186+
'server_tools' => [
187+
'url_context' => true,
188+
'google_search' => true
189+
],
190+
'temperature' => 0.7
191+
]);
192+
193+
// Optional: Add custom tools
194+
$toolbox = Toolbox::create(new Clock());
195+
$processor = new ChainProcessor($toolbox);
196+
197+
// Create chain
198+
$chain = new Chain($platform, $llm);
199+
200+
// Use with URL context
201+
$messages = new MessageBag(
202+
Message::ofUser(
203+
'Compare the current EUR/USD exchange rate from https://www.xe.com with historical rates.
204+
What has been the trend over the past month?'
205+
)
206+
);
207+
208+
$response = $chain->call($messages);
209+
echo $response->getContent() . PHP_EOL;
210+
```
211+
212+
## Limitations
213+
214+
- Server tools are only available for Google Gemini models
215+
- API key must have appropriate permissions
216+
- Server tools may have usage quotas
217+
- Response times may vary based on the complexity of server tool operations
218+
- Not all Gemini model versions support all server tools
219+
220+
## Future Considerations
221+
222+
As the feature evolves, consider:
223+
224+
- Additional server tools may become available
225+
- Parameters for existing tools may be expanded
226+
- Integration patterns may be refined based on usage

0 commit comments

Comments
 (0)