Codificación agente basada en ingeniería de costos: Creación de un sistema de nivel producción
Codificación agente basada en ingeniería de costos: una configuración local de LLM de nivel profesional con enrutamiento LiteLLM, caché de prompts y puntos de conexión compatibles con OpenAI que reducen los gastos.
Esta guía reconstruye el proceso desde las materias primas hasta un sistema funcional para: Codificación agente basada en análisis de costos: creación de un proxy local de LLM de nivel industrial, arquitectura multiagente y herramientas seguras con Zoo Code, TensorX y DeepInfra. El enfoque está en pasos operativos claros, verificaciones explícitas y código que se puede incorporar directamente a un repositorio sin necesidad de adivinar su propósito.
Resumen ejecutivo
Para el resumen ejecutivo, defina las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Registre los tiempos de ejecución y el costo en tokens o consultas junto con los resultados funcionales. Tener visibilidad de los costos desde el inicio evita facturas inesperadas cuando el proceso pasa de una demostración a entornos compartidos. Prefiera salidas estructuradas con validación de esquema sobre texto libre cuando el siguiente paso sea escribir código o realizar una llamada a una herramienta.
1. Visión general arquitectónica: El patrón de proxy local
En la sección 1. Visión general arquitectónica: El patrón de proxy local, se deben definir las entradas, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea a partir de un punto de control conocido sin tener que adivinar el estado oculto. Se debe mantener la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un único lugar que los operadores puedan auditar sin necesidad de leer todo el sistema. Se prefiere un formato de salida estructurado con validación de esquema sobre texto libre cuando el siguiente paso sea la ejecución de código o una llamada a una herramienta.
Capa de traducción de protocolos
Para la capa de traducción de protocolos, defina las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Documente tanto la ruta óptima como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Prefiera salidas estructuradas con validación de esquema sobre texto en formato libre cuando el siguiente paso sea escribir código o realizar una llamada a una herramienta.
2. Configuración principal: Análisis detallado de litellm_config.yaml
Para el nivel 2: Configuración avanzada. Analice en profundidad litellm_config.yaml, defina las entradas, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea a partir de un punto de control conocido sin tener que adivinar el estado oculto. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando una tarea falla, el error debe indicar una única responsabilidad y no un proceso complicado. Opte por salidas estructuradas con validación de esquema en lugar de texto libre cuando el paso siguiente sea código o una llamada a una herramienta.
# litellm_config.yaml
litellm_settings:
drop_params: true
modify_params: true
model_list:
# =========================================================================
# WILDCARD CATCH-ALL ROUTES
# Allows on-the-fly usage of any model published by TensorX or DeepInfra
# Example: tensorx/qwen/qwen3.8-2.4t-a95b
# =========================================================================
- model_name: "tensorx/*"
litellm_params:
model: "openai/*"
api_base: https://api.tensorx.ai/v1
api_key: "PLACEHOLDER_TENSORX_KEY"
use_chat_completions_api: true
- model_name: "deepinfra/*"
litellm_params:
model: "openai/*"
api_base: https://api.deepinfra.com/v1/openai
api_key: "PLACEHOLDER_DEEPINFRA_KEY"
use_chat_completions_api: true
# =========================================================================
# TENSORX NAMED SHORT ALIASES
# =========================================================================
- model_name: kimi-k3
litellm_params:
model: openai/moonshotai/kimi-k3
api_base: https://api.tensorx.ai/v1
api_key: "PLACEHOLDER_TENSORX_KEY"
use_chat_completions_api: true
- model_name: glm-5.2
litellm_params:
model: openai/z-ai/glm-5.2
api_base: https://api.tensorx.ai/v1
api_key: "PLACEHOLDER_TENSORX_KEY"
use_chat_completions_api: true
- model_name: kimi-k2.7-code
litellm_params:
model: openai/moonshotai/kimi-k2.7-code
api_base: https://api.tensorx.ai/v1
api_key: "PLACEHOLDER_TENSORX_KEY"
use_chat_completions_api: true
- model_name: glm-5.1
litellm_params:
model: openai/z-ai/glm-5.1
api_base: https://api.tensorx.ai/v1
api_key: "PLACEHOLDER_TENSORX_KEY"
use_chat_completions_api: true
# =========================================================================
# DEEPINFRA NAMED SHORT ALIASES
# =========================================================================
- model_name: deepseek-v4-pro
litellm_params:
model: openai/deepseek-ai/DeepSeek-V4-Pro
api_base: https://api.deepinfra.com/v1/openai
api_key: "PLACEHOLDER_DEEPINFRA_KEY"
use_chat_completions_api: true
- model_name: qwen3-coder-480b
litellm_params:
model: openai/Qwen/Qwen3-Coder-480B-A35B-Instruct
api_base: https://api.deepinfra.com/v1/openai
api_key: "PLACEHOLDER_DEEPINFRA_KEY"
use_chat_completions_api: true
- model_name: qwen3.6-35b
litellm_params:
model: openai/Qwen/Qwen3.6-35B-A3B
api_base: https://api.deepinfra.com/v1/openai
api_key: "PLACEHOLDER_DEEPINFRA_KEY"
use_chat_completions_api: true
- model_name: glm-4.7-flash
litellm_params:
model: openai/zai-org/GLM-4.7-Flash
api_base: https://api.deepinfra.com/v1/openai
api_key: "PLACEHOLDER_DEEPINFRA_KEY"
use_chat_completions_api: true
- model_name: nemotron-3-ultra
litellm_params:
model: openai/nvidia/Nemotron-3-Ultra
api_base: https://api.deepinfra.com/v1/openai
api_key: "PLACEHOLDER_DEEPINFRA_KEY"
use_chat_completions_api: true
# =========================================================================
# PROXY AUTHENTICATION GATEWAY
# =========================================================================
general_settings:
master_key: "PLACEHOLDER_MASTER_KEY"
Mecánicas críticas de configuración
En el caso de las mecánicas de configuración críticas, defina los insumos, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Trate esta etapa como un contrato entre los insumos y los resultados validados. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Prefiera resultados estructurados con validación de esquema sobre textos en formato libre cuando el siguiente paso sea escribir código o realizar una llamada a una herramienta. En el caso de las mecánicas de configuración críticas, defina los insumos, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar que los operadores puedan auditar sin necesidad de leer todo el sistema.
3. Modelado de amenazas y seguridad por defensa en profundidad
Al trabajar en la sección 3. Modelado de amenazas y seguridad por defensa en profundidad, primero anote el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Documente tanto el camino óptimo como el de recuperación. Los intentos repetidos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Almacene en caché las instrucciones estables del sistema y los esquemas de las herramientas. Reenviar un preámbulo idéntico es una causa común de problemas.
El patrón de vulnerabilidad Open Relay
Al trabajar con el patrón de vulnerabilidad The Open Relay, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Prefiera unidades pequeñas y probables sobre scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad y no a un proceso complicado. Almacene en caché las instrucciones del sistema estables y los esquemas de las herramientas. Reenviar un preámbulo idéntico es una causa común de sobrecarga.
El estándar de mitigación de doble capa
Al trabajar con la Norma de Mitigación de Doble Capa, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Considere esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina las comprobaciones de éxito y evite completaciones parciales silenciosas. Almacene en caché las instrucciones del sistema estables y los esquemas de las herramientas. Reenviar un preámbulo idéntico es una causa común de sobrecarga. Al trabajar con la Norma de Mitigación de Doble Capa, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema.
# Executable Proxy Invocation Command
LITELLM_USE_CHAT_COMPLETIONS_URL_FOR_ANTHROPIC_MESSAGES=true \
litellm --config ~/.claude/litellm_config.yaml \
--host 127.0.0.1 \
--port 4000
# Authentication Enforcement inside litellm_config.yaml
general_settings:
master_key: "sk-7i9UOL9jkji09löOIhM..."
Arquitectura de Separación de Secretos
La Arquitectura de Separación de Secretos funciona mejor cuando se trata como una superficie medible. Capture una transcripción clave, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el de recuperación juntos. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Asigne un presupuesto de tokens por turno y por sesión. Las herramientas agenciales amplían el contexto de manera excesiva; los límites estrictos evitan que las demostraciones se conviertan en facturas inesperadas.
4. Ingeniería de Costos Multiagente: Orquestador, Explorador y Programador Económico
- Ingeniería de costos multiagente: Orchestrator, Scout y Cheap Coder funcionan mejor cuando se tratan como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando falla un paso, el fallo debe apuntar a una sola responsabilidad y no a un proceso complicado. Asigne un presupuesto de tokens por turno y por sesión. Las herramientas agentes amplían el contexto de manera excesiva; los límites estrictos evitan que las demostraciones se conviertan en facturas inesperadas.
El problema del crecimiento excesivo del contexto en los sistemas agentes
El problema del crecimiento excesivo del contexto agente funciona mejor cuando se trata como un aspecto medible. Capture una transcripción ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Considere esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace completaciones parciales silenciosas. Asigne un presupuesto de tokens por turno y por sesión. Las herramientas agente amplían el contexto de forma agresiva; los límites máximos evitan que las demostraciones se conviertan en facturas inesperadas. El problema del crecimiento excesivo del contexto agente funciona mejor cuando se trata como un aspecto medible. Capture una transcripción ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar que los operadores puedan auditar sin tener que leer todo el sistema.
La solución de tres agentes
Para la solución de tres agentes, defina las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Documente tanto la ruta óptima como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Prefiera salidas estructuradas con validación de esquema sobre texto libre cuando el siguiente paso sea escribir código o hacer una llamada a una herramienta.
Comparación de costos por contexto
Para una comparación de costos en contexto, defina las entradas, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea desde un punto de control conocido sin tener que adivinar el estado oculto. Prefiera unidades pequeñas y verificables sobre scripts extensos. Cuando una tarea falla, el error debe indicar una única responsabilidad y no un proceso complicado. Prefiera salidas estructuradas con validación de esquema sobre texto libre cuando el paso siguiente sea código o una llamada a una herramienta.
Declaraciones de modo personalizado (custom_modes.yaml)
Para las declaraciones de modo personalizado (custom_modes.yaml), defina las entradas, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea a partir de un punto de control conocido sin tener que adivinar el estado oculto.
Trate esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas.
Prefiera resultados estructurados con validación de esquema sobre texto en formato libre cuando el siguiente paso sea código o una llamada a una herramienta.
Para las declaraciones de modo personalizado (custom_modes.yaml), defina las entradas, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea a partir de un punto de control conocido sin tener que adivinar el estado oculto.
Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar que los operadores puedan auditar.
customModes:
- slug: scout
name: 🔍 Scout
roleDefinition: >-
You are a reconnaissance specialist. The orchestrator cannot read files,
so you read them on its behalf and return the smallest set of facts it
needs to write a precise implementation brief: exact paths, exact symbol
locations, and only the excerpts that matter.
whenToUse: >-
Use as the first subtask whenever the orchestrator does not already know
the exact file paths and code shape involved. Always run a scout before
delegating implementation into a codebase area that has not been mapped.
groups:
- read
customInstructions: >-
WHY YOU EXIST: Your report is pasted into the orchestrator's context,
which runs on the most expensive model in this system. Raw file dumps
read there cost many times what they cost here. Your job is to convert
a lot of cheap reading into a little expensive context.
WHAT TO RETURN: Exact repo-relative paths with line numbers. The signature
or declaration of every symbol that matters. Only excerpts directly relevant
to the task. Maximum budget: ~40 lines of total quoted code across all files.
NEVER paste full files. NEVER suggest solutions or fixes—report facts only.
- slug: cheap-coder
name: 💸 Cheap Coder
roleDefinition: >-
You are a focused implementation worker. You receive a precise,
self-contained task brief from an orchestrator and apply the smallest
correct code change that satisfies it. You do not design architecture,
you do not explore the repository on your own, and you do not invent requirements.
whenToUse: >-
Use for delegated single-purpose implementation subtasks whose target files
and intent are already named in the brief. Do not use for investigation
or architectural design.
groups:
- read
- edit
- command
customInstructions: >-
SCOPE: Work only from the files and excerpts named in your task brief.
Do not search or browse the repository to build your own picture; the
orchestrator already paid for exploration and passed you the result.
If the brief is missing a file or fact, stop and report exactly what is
missing instead of hunting for it.
EDITS: Apply the minimal diff that satisfies the brief. Preserve surrounding
style, type annotations, and conventions. Run only the single verification
command specified in the brief. If verification fails twice, stop and report.
Instrucciones personalizadas de Orchestrator
Al trabajar con las instrucciones personalizadas de Orchestrator, anote primero el contrato: entradas requeridas, señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Documente junto con ello el camino óptimo y el camino de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Almacene en caché las instrucciones estables del sistema y los esquemas de herramientas. Reenviar un preámbulo idéntico es una causa común de agotamiento.
You cannot read files. Before delegating any implementation into code you have
not yet mapped, delegate a `scout` subtask first and use its report to write the
implementation brief.
Delegate implementation with new_task to `cheap-coder`, never to `code`. Every
brief must be self-contained—the worker cannot see this conversation. Include:
the exact file paths from the scout report, the excerpts the scout returned, the
precise change wanted, and the single verification command to run.
Never paste a scout report into a brief wholesale; pass only the part that
subtask needs.
After an implementation subtask reports success, do not accept its self-assessment.
Delegate a separate `scout` subtask to verify: have it confirm the changed files now
contain what was asked and report the verification command's output verbatim. Decide
on the scout's facts, not the implementer's summary.
Once the scout's verification confirms the change is correct, use
ask_followup_question to ask the user for permission to commit, and separately ask
for permission to push—approval of one is never approval of the other. If the user
approves committing, delegate to `cheap-coder` with a brief naming only the exact
relative paths of the files that actually changed to stage (never `git add .` or
`git add -A`) and the exact commit message to use: a single short line, imperative
mood, no `Co-Authored-By` trailer, no "Generated with" attribution line. Only include
a push step in that brief if the user separately approved pushing.
5. Economía del modelo y aprovechamiento del caché de prompts
Al trabajar en la sección 5. Model Economics and Prompt Caching Leverage, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el fallo debe apuntar a una sola responsabilidad y no a un proceso complicado. Almacene en caché las instrucciones del sistema estables y los esquemas de las herramientas. Reenviar un preámbulo idéntico es una causa común de desperdicio.
Modelo destacado: qwen3.8-2.4t-a95b (TensorX)
Al trabajar con Model Spotlight: qwen3.8-2.4t-a95b (TensorX), anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código.
Considere esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina comprobaciones de éxito y evite completaciones parciales silenciosas.
Almacene en caché las instrucciones del sistema estables y los esquemas de las herramientas. Reenviar un preámbulo idéntico es una causa común de desperdicio.
La mecánica del caché de prompts
Al trabajar en “The Mechanics of Prompt Caching”, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Registre los tiempos y el costo en tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el entorno pasa de la versión de demostración a entornos compartidos. Almacene en caché las instrucciones del sistema estables y los esquemas de las herramientas. Reenviar un preámbulo idéntico es una causa común de consumo excesivo.
Turn 1: [System Prompt + Tool Definitions + File Map] -> Written to Cache ($2.50 / 1M)
Turn 2: [System Prompt + Tool Definitions + File Map] -> CACHE HIT ($0.63 / 1M) -> 75% Savings
Turn 3: [System Prompt + Tool Definitions + File Map] -> CACHE HIT ($0.63 / 1M) -> 75% Savings
6. Telemetría, privacidad y auditoría de ejecución local
Al trabajar en la sección 6: Telemetría, Privacidad y Auditoría de Ejecución Local, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación ayuda a mantener honestas las futuras modificaciones del código. Guarde la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben encontrarse en un lugar donde los operadores puedan realizar auditorías sin tener que leer todo el código. Almacene en caché las instrucciones del sistema estables y los esquemas de las herramientas. Reenviar un preámbulo idéntico es una causa común de consumo excesivo de recursos.
Resultados de la auditoría
Al trabajar en los hallazgos de auditoría, anote primero el contrato: los datos necesarios, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Documente junto con ello el camino óptimo y el camino de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Almacene en caché las instrucciones estables del sistema y los esquemas de las herramientas. Reenviar un preámbulo idéntico es una causa común de agotamiento.
Reforzando la telemetría hasta cero
Al trabajar en el proceso de endurecimiento de la telemetría hasta niveles mínimos, anote primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación ayuda a mantener honestas las futuras modificaciones del código. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el fallo debe indicar una única responsabilidad y no un proceso complicado. Almacene en caché las instrucciones del sistema estables y los esquemas de las herramientas. Reenviar un preámbulo idéntico es una causa común de problemas.
{
"telemetry.telemetryLevel": "off"
}
7. Guía paso a paso para la configuración en producción
Al trabajar en la Guía paso a paso para la configuración de producción 7, anote primero el contrato: los insumos requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Considere esta etapa como un contrato entre los insumos y los resultados validados. Asigne nombres a los artefactos, defina las verificaciones de éxito y evite completaciones parciales silenciosas. Almacene en caché las instrucciones del sistema estables y los esquemas de las herramientas. Reenviar un preámbulo idéntico es una causa común de problemas.
Paso 1: Inicialización del entorno
Al trabajar en el Paso 1: Inicialización del entorno, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando se pasa de entornos de demostración a entornos compartidos. Almacene en caché las instrucciones del sistema estables y los esquemas de herramientas. Reenviar un preámbulo idéntico es una causa común de gastos innecesarios.
# Start LiteLLM Proxy in foreground
alias claude-proxy='LITELLM_USE_CHAT_COMPLETIONS_URL_FOR_ANTHROPIC_MESSAGES=true litellm --config ~/.claude/litellm_config.yaml --host 127.0.0.1 --port 4000'
# Start LiteLLM Proxy in background with health check
cx-proxy-up() {
if ! ss -ltn | grep -q ":4000 "; then
echo "Starting LiteLLM Proxy on 127.0.0.1:4000..."
LITELLM_USE_CHAT_COMPLETIONS_URL_FOR_ANTHROPIC_MESSAGES=true \
nohup litellm --config ~/.claude/litellm_config.yaml --host 127.0.0.1 --port 4000 > /tmp/litellm-proxy.log 2>&1 &
# Wait for readiness endpoint
until curl -s http://127.0.0.1:4000/health/readiness | grep -q '"status":"healthy"'; do
sleep 0.5
done
echo "LiteLLM Proxy is online and healthy."
else
echo "LiteLLM Proxy is already running on port 4000."
fi
}
# CLI model catalog search tool
cx-find() {
python3 ~/.claude/cx-find.py "$@"
}
source ~/.bashrc
Paso 2: Inicializar el proxy
Al trabajar en el Paso 2: Inicializar el proxy, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación ayuda a mantener honestas las futuras modificaciones del código. Guarde la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema. Almacene en caché las instrucciones del sistema estables y los esquemas de las herramientas. Reenviar un preámbulo idéntico es una causa común de consumo excesivo.
cx-proxy-up
ss -ltnp | grep :4000
# Expected output: LISTEN 0 128 127.0.0.1:4000 ...
curl -s http://127.0.0.1:4000/health/readiness
# Expected output: {"status":"healthy","db":"Not connected"}
Paso 3: Configurar perfiles de extensión de código Zoo
Al trabajar en el Paso 3: Configurar perfiles de extensión Zoo Code, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Documente junto con ello el camino óptimo y el camino de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Almacene en caché las instrucciones estables del sistema y los esquemas de las herramientas. Reenviar un preámbulo idéntico es una causa común de problemas.
Perfiles
Al trabajar con perfiles, anote primero el contrato: los datos requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación ayuda a mantener honestas las futuras modificaciones en el código. Prefiera unidades pequeñas y verificables a scripts extensos. Cuando un paso falla, el fallo debe referirse a una sola responsabilidad y no a un proceso complicado. Almacene en caché las instrucciones del sistema estables y los esquemas de las herramientas. Reenviar un preámbulo idéntico es una causa común de problemas.
Paso 4: Vinculaciones entre modos y perfiles
Al trabajar en el Paso 4: Vinculaciones de modo a perfil, anote primero el contrato: entradas requeridas, señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Trate esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina comprobaciones de éxito y evite completaciones parciales silenciosas. Almacene en caché las instrucciones del sistema estables y los esquemas de herramientas. Reenviar un preámbulo idéntico es una causa común de desperdicio. Al trabajar en el Paso 4: Vinculaciones de modo a perfil, anote primero el contrato: entradas requeridas, señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema.
🪃 Orchestrator --> orchestrator profile
🔍 Scout --> worker profile
💸 Cheap Coder --> worker profile
Debug --> orchestrator profile
8. Guía de verificación y resolución de problemas
- La Guía de verificación y resolución de problemas funciona mejor cuando se trata como una superficie medible. Capture una transcripción exitosa, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el camino de recuperación juntos. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son ajustes realizados posteriormente. Asigne un presupuesto de tokens por turno y por sesión. Las herramientas agenciales amplían el contexto de manera excesiva; los límites máximos evitan que las demostraciones se conviertan en facturas inesperadas.
Verificación de modelos activos
Verificar los modelos activos funciona mejor cuando se trata como una superficie medible. Capture un transcripte exitoso, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiera unidades pequeñas y probables sobre scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad en lugar de a un proceso complicado. Asigne un presupuesto de tokens por turno y por sesión; las herramientas agentes amplían el contexto de forma excesiva; los límites estrictos evitan que las demostraciones se conviertan en facturas inesperadas.
curl -si http://localhost:4000/v1/messages \
-H "Authorization: Bearer YOUR_MASTER_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"kimi-k3","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}' \
| grep -i x-litellm
Códigos de error comunes y soluciones
Códigos de error comunes y soluciones funcionan mejor cuando se consideran como una superficie medible. Capture una transcripción ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Trate esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace completaciones parciales silenciosas. Asigne un presupuesto de tokens por turno y por sesión; las herramientas agentes amplían el contexto de forma excesiva; los límites máximos evitan que las demostraciones se conviertan en facturas inesperadas.
Error: HTTP 400 No connected db. / HTTP 500 Internal Server Error
Error: HTTP 403 Key not allowed to access model
Error: Safe Process Termination durante Proxy restarts
OLD_PID=$(ss -ltnp | grep ":4000" | grep -oE "pid=[0-9]+" | cut -d= -f2 | head -1)
if [ -n "$OLD_PID" ]; then
kill "$OLD_PID"
sleep 2
ss -ltn | grep -q ":4000" || echo "Port 4000 cleared successfully."
fi
Conclusión
Lista de verificación operativa
Lecturas relacionadas
- Notas prácticas: Construyendo un agente de programación en nube privada: OpenCode + un LLM local — Guía paso a paso de las Notas prácticas: Construyendo un agente de programación en nube privada: OpenCode + un LLM local: contratos, verificaciones y espacios de código listos para usar para los equipos que implementan este patrón.
- Notas prácticas: MCP para desarrolladores de LangGraph: De lo básico a la producción — Guía paso a paso de las Notas prácticas: MCP para desarrolladores de LangGraph: De lo básico a la producción: contratos, verificaciones y espacios de código listos para usar para los equipos que implementan este patrón.