El sistema de registro de herramientas de Pi Agent falla silenciosamente cuando el esquema de su herramienta no coincide con el formato esperado. Registra una herramienta de búsqueda personalizada, pero Pi nunca la llama, sino que recurre a su conocimiento incorporado. Este tutorial analiza los tres errores de registro más comunes: formato de esquema de entrada incorrecto, campos de descripción obligatorios faltantes y discrepancias en las firmas de funciones. Luego muestra cómo registrar una herramienta de búsqueda Scavio que funcione y que Pi realmente utilizará para la conexión a tierra web.
Requisitos previos
- Python 3.9+ instalado
- solicita biblioteca instalada
- Una clave API de Scavio de scavio.dev
- SDK del Agente Pi instalado
Guia paso a paso
Paso 1: Diagnostica por qué Pi ignora tu herramienta
Consulte las tres razones más comunes por las que Pi Agent rechaza una herramienta registrada: errores de validación de esquema, campos faltantes y tipos incorrectos.
Python
import os, requests, json
SCAVIO_KEY = os.environ['SCAVIO_API_KEY']
# BROKEN: Pi ignores this tool because inputSchema uses 'args' instead of 'properties'
broken_tool = {
'name': 'web_search',
'description': 'Search the web',
'inputSchema': {
'type': 'object',
'args': {'query': {'type': 'string'}} # WRONG: should be 'properties'
}
}
# FIXED: Correct schema format Pi expects
fixed_tool = {
'name': 'web_search',
'description': 'Search the web for current information using Scavio API. Use this tool when the user asks about recent events, current data, or anything that requires up-to-date information.',
'inputSchema': {
'type': 'object',
'properties': {
'query': {'type': 'string', 'description': 'The search query'}
},
'required': ['query']
}
}
# Validate your tool schema
def validate_tool_schema(tool: dict) -> list:
errors = []
if not tool.get('name'): errors.append('Missing tool name')
if not tool.get('description'): errors.append('Missing description')
if len(tool.get('description', '')) < 20: errors.append('Description too short (Pi needs context to decide when to use the tool)')
schema = tool.get('inputSchema', {})
if schema.get('type') != 'object': errors.append('inputSchema.type must be object')
if 'properties' not in schema: errors.append('Missing inputSchema.properties (common: using args instead)')
return errors
print('Broken tool errors:', validate_tool_schema(broken_tool))
print('Fixed tool errors:', validate_tool_schema(fixed_tool))Paso 2: Registre una herramienta de búsqueda Scavio que funcione
Cree y registre una herramienta de búsqueda con el esquema correcto y una descripción detallada que le indique a Pi cuándo usarla.
Python
H = {'x-api-key': SCAVIO_KEY, 'Content-Type': 'application/json'}
def scavio_search(query: str) -> str:
"""Search the web via Scavio API."""
resp = requests.post('https://api.scavio.dev/api/v1/search',
headers=H, json={'query': query, 'country_code': 'us', 'num_results': 5})
resp.raise_for_status()
results = resp.json().get('organic_results', [])
return '\n\n'.join(f'{r["title"]}\n{r.get("snippet", "")}\n{r["link"]}' for r in results)
# Tool definition Pi will accept
search_tool_def = {
'name': 'web_search',
'description': 'Search the web for current information. Use when the user asks about recent events, pricing, comparisons, or anything requiring fresh data. Returns titles, snippets, and URLs.',
'inputSchema': {
'type': 'object',
'properties': {
'query': {
'type': 'string',
'description': 'The search query to look up'
}
},
'required': ['query']
}
}
# Test the tool works before registering
result = scavio_search('best search api 2026')
print(f'Tool test passed: {len(result)} chars returned')
print(result[:200])Paso 3: Conecte la herramienta al bucle de ejecución del Agente Pi
Registre la herramienta con Pi Agent y maneje las respuestas a las llamadas de la herramienta. Cuando Pi decida utilizar su herramienta, ejecútela y envíe los resultados.
Python
TOOL_HANDLERS = {
'web_search': scavio_search,
}
def handle_pi_tool_call(tool_name: str, arguments: dict) -> str:
handler = TOOL_HANDLERS.get(tool_name)
if not handler:
return f'Unknown tool: {tool_name}'
try:
return handler(**arguments)
except Exception as e:
return f'Tool error: {str(e)}'
# Simulate a Pi tool call
result = handle_pi_tool_call('web_search', {'query': 'latest python frameworks 2026'})
print('Pi tool call result:')
print(result[:300])Paso 4: Pruebe de un extremo a otro con Pi Agent
Ejecute una interacción completa en la que Pi recibe una pregunta, decide llamar a su herramienta de búsqueda y utiliza los resultados para generar una respuesta.
Python
def test_pi_with_search(prompt: str):
"""Simulate Pi Agent with search tool."""
print(f'User: {prompt}')
print(f'Pi detects need for current information...')
# Pi would call the tool here
search_result = handle_pi_tool_call('web_search', {'query': prompt})
print(f'Tool returned {len(search_result)} chars')
print(f'Pi generates grounded response using search results')
print(f'\nSearch data preview:')
print(search_result[:300])
print(f'\nCost: $0.005 (1 Scavio credit)')
test_pi_with_search('What are the best Python web frameworks in 2026?')Ejemplo en Python
Python
import os, requests
SCAVIO_KEY = os.environ['SCAVIO_API_KEY']
H = {'x-api-key': SCAVIO_KEY, 'Content-Type': 'application/json'}
def scavio_search(query):
resp = requests.post('https://api.scavio.dev/api/v1/search', headers=H,
json={'query': query, 'country_code': 'us', 'num_results': 5})
return resp.json().get('organic_results', [])
# Correct tool schema for Pi Agent
tool_def = {
'name': 'web_search',
'description': 'Search the web for current information. Use for recent events, pricing, and comparisons.',
'inputSchema': {
'type': 'object',
'properties': {'query': {'type': 'string', 'description': 'Search query'}},
'required': ['query']
}
}
results = scavio_search('best python frameworks 2026')
print(f'Search returned {len(results)} results')
for r in results[:3]:
print(f' {r["title"]}')Ejemplo en JavaScript
JavaScript
const SCAVIO_KEY = process.env.SCAVIO_API_KEY;
async function scavioSearch(query) {
const resp = await fetch('https://api.scavio.dev/api/v1/search', {
method: 'POST',
headers: { 'x-api-key': SCAVIO_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({ query, country_code: 'us', num_results: 5 })
});
return (await resp.json()).organic_results || [];
}
// Correct tool schema for Pi Agent
const toolDef = {
name: 'web_search',
description: 'Search the web for current information.',
inputSchema: {
type: 'object',
properties: { query: { type: 'string', description: 'Search query' } },
required: ['query']
}
};
scavioSearch('best python frameworks 2026').then(r => {
console.log(`${r.length} results`);
r.slice(0, 3).forEach(x => console.log(` ${x.title}`));
});Salida esperada
JSON
Broken tool errors: ['Missing inputSchema.properties (common: using args instead)']
Fixed tool errors: []
Tool test passed: 842 chars returned
Top Python Web Frameworks in 2026
Django, FastAPI, and Litestar lead the...
https://example.com/python-frameworks
Pi tool call result:
Top Python Web Frameworks in 2026
Django, FastAPI, and Litestar lead the pack...
Cost: $0.005 (1 Scavio credit)