Server-Side Tools
Enable and observe provider-native tools (e.g., OpenAI Responses server-side tools) with a single switch.
Server-side tools are capabilities executed by the provider (not your app). Examples include web search, file/document search, browser/desktop control, image generation, and code interpreter. When enabled, the model decides when to use them, the provider runs them, and results appear in the streaming response.
Key benefits
- Zero hosting: No code to run or maintain for these tools.
- Lower latency: Single round-trip; results stream as they’re produced.
- Rich signals: Structured SSE events and media deltas.
Enable server-side tools (OpenAI Responses)
import 'package:dartantic_ai/dartantic_ai.dart';
final agent = Agent(
'openai-responses:gpt-4o',
chatModelOptions: const OpenAIResponsesChatOptions(
serverSideTools: {OpenAIServerSideTool.webSearch, OpenAIServerSideTool.imageGeneration},
),
);
Observing usage in metadata
When tools are used, the stream carries metadata-only events so you can drive UI, telemetry, or governance without interfering with the model flow.
await for (final chunk in agent.sendStream('Search for recent news')) {
if (chunk.output.isNotEmpty) stdout.write(chunk.output);
// Optional observability hooks - metadata is automatically truncated for display
final web = chunk.metadata['web_search'];
if (web != null) {
// { stage: 'in_progress'|'searching'|'completed', data: {...} }
print('\n[web_search/${web['stage']}] ${web['data']}');
}
final ig = chunk.metadata['image_generation'];
if (ig != null) {
// { stage: 'in_progress'|'generating'|'partial_image'|'completed', data: {...} }
print('\n[image_generation/${ig['stage']}] ${ig['data']}');
}
// Image data comes through as DataPart or LinkPart
for (final msg in chunk.messages) {
for (final part in msg.parts) {
if (part is DataPart && part.mimeType.startsWith('image/')) {
// Handle image bytes
print('Received image: ${part.bytes.length} bytes');
} else if (part is LinkPart) {
print('Image URL: ${part.url}');
}
}
}
}
Provider note (OpenAI Responses)
- These map directly to OpenAI's server-side tools (web_search, file_search, computer_use, image_generation, code_interpreter).
- Image generation streams
partial_image_b64data which is accumulated and emitted asDataParton completion. - Web search doesn't include the search query in metadata - the provider handles the search internally.
Advanced configuration
- For provider-specific tuning (e.g., file/web search filters), supply per-tool config on
OpenAIResponsesChatOptions.
import 'package:dartantic_ai/dartantic_ai.dart';
final agent = Agent(
'openai-responses:gpt-4o',
chatModelOptions: OpenAIResponsesChatOptions(
serverSideTools: const {OpenAIServerSideTool.webSearch},
webSearchConfig: const WebSearchConfig(
siteFilter: 'site:developer.apple.com',
),
),
);
Why not callbacks?
Server-side tools are already executed by the provider and feed the model directly. Callbacks are not required for model quality. Metadata is exposed purely for product UX, analytics, and compliance.