Cómo utilizar la IA de Pydantic con FXMacroData: agentes de tipo, REST y MCP

El Pydántico AI Es útil para los agentes de investigación de FX cuando la parte más difícil no es llamar a un modelo, sino hacer que el modelo devuelva una salida escrita y revisable. calendarios de lanzamiento, el historial de anuncios, El valor de la moneda de referencia contexto, El COT el posicionamiento, productos básicos, y Sesión de divisas datos.

La separación del núcleo es simple. Pydantic AI coordina el modelo, las herramientas, las dependencias de tipo y la salida final. FXMacroData responde a las preguntas de datos de mercado: qué se imprimió, cuándo se imprimía, cuál fue el valor anterior, qué se programa a continuación y qué panel de control puede inspeccionar un humano. Eso importa para Indicador de precios de los Estados Unidos¿ Qué ? Pago de los trabajadores no agrícolas¿ Qué ? Tasa de política de la Reserva Federal decisión, o una El valor de las pérdidas Nota de riesgo de liberación.

Por qué Pydantic AI se adapta a los agentes de macro FX

Los agentes de IA de Pydantic son contenedores para instrucciones, herramientas de funciones, conjuntos de herramienta, tipos de salida estructurados, dependencias, modelos, configuraciones y capacidades reutilizables.

El valor práctico es la validación. Pydantic AI puede utilizar herramientas de funciones para recuperar datos, modelos Pydantics para dar forma a la respuesta final y validadores de salida cuando una respuesta carece de campos obligatorios. FXMacroData luego suministra las filas de macro actuales sobre las que el modelo debe razonar.

REST, herramientas de tipo, salida estructurada o MCP: qué ruta utilizar

La mayoría de los equipos deben comenzar con REST porque mantiene credenciales, intentos de reutilización, almacenamiento en caché y registros en el código de la aplicación. Agregue herramientas de IA Pydantic cuando el modelo deba decidir qué función de datos de solo lectura llamar. Agregar salida estructurada de la primera versión. Utilice MCP cuando un servidor de herramienta alojada reutilizable sea mejor que los envases locales.

Los requisitos previos

Necesita Python, Pydantic AI, un proveedor de modelos configurado, una clave de API FXMacroData y un flujo de trabajo estrecho.

pip install pydantic-ai requests
pip install "pydantic-ai-slim[mcp]"

Para las comprobaciones directas de REST, utilizar los puntos finales de producción FXMacroData y la autenticación de parámetros de consulta:

curl "https://api.fxmacrodata.com/v1/calendar/usd?api_key=YOUR_API_KEY"
curl "https://api.fxmacrodata.com/v1/announcements/usd/inflation?api_key=YOUR_API_KEY"
curl "https://api.fxmacrodata.com/v1/forex/eur/usd?api_key=YOUR_API_KEY"
curl "https://api.fxmacrodata.com/v1/commodities/latest?api_key=YOUR_API_KEY"

El modelo debe recibir pruebas y rutas de origen, no credenciales.

Paso 1: Definir el contrato de información tipográfica

Qué hacer: Define el objeto final que quieres que el agente devuelva antes de colocar las herramientas.

from pydantic import BaseModel, Field

class MacroBriefing(BaseModel):
    currency: str = Field(pattern="^[A-Z]{3}$")
    topic: str
    evidence_used: list[str] = Field(min_length=1)
    key_values: list[str] = Field(min_length=1)
    interpretation: str
    data_gaps: list[str] = Field(default_factory=list)
    human_review_required: bool = True

El esquema de salida es intencionalmente pequeño. Una primera versión debe demostrar que el agente puede buscar evidencia, nombrarla y separar la interpretación de los datos faltantes. Añadir campos más tarde cuando un flujo de trabajo del usuario los necesite.

Paso 2: Añadir FXMacroData como una herramienta de IA de Pydantic

Qué hacer: Las herramientas de IA pydantic son útiles cuando el modelo necesita información adicional que debería provenir del código de aplicación determinista.

from dataclasses import dataclass
import os
import requests

@dataclass
class FxmdDeps:
    api_key: str
    api_root: str = "https://api.fxmacrodata.com/v1"

def fxmd_get(deps: FxmdDeps, path: str) -> dict:
    response = requests.get(
        f"{deps.api_root}/{path}",
        params={"api_key": deps.api_key},
        timeout=10,
    )
    response.raise_for_status()
    return response.json()

Se fija el envoltorio a un agente con un tipo de salida estructurado:

from pydantic_ai import Agent, RunContext

agent = Agent(
    "openai:gpt-5-mini",
    deps_type=FxmdDeps,
    output_type=MacroBriefing,
    instructions=(
        "Use FXMacroData before writing about current macro data. "
        "Return endpoint paths, values, interpretation, and gaps."
    ),
)

@agent.tool
def fxmacrodata_calendar(ctx: RunContext[FxmdDeps], currency: str) -> dict:
    """Fetch confirmed macro calendar rows for a 3-letter currency."""
    code = currency.lower().strip()
    return {"endpoint": f"/v1/calendar/{code}", "data": fxmd_get(ctx.deps, f"calendar/{code}")}

deps = FxmdDeps(api_key=os.environ["FXMD_API_KEY"])
result = agent.run_sync("Prepare a USD release briefing.", deps=deps)
print(result.output.model_dump())

Mantenga los nombres de las herramientas estrechos. Un primer agente puede exponer solo datos de calendario. Agregue el historial de anuncios, el contexto de pares de divisas, COT, productos básicos o sesiones cuando la pregunta los necesite.

Un esquema de herramientas mínimo debe ser fácil de inspeccionar para el modelo y los revisores:

{
  "name": "fxmacrodata_calendar",
  "description": "Fetch confirmed macro calendar rows for a currency.",
  "parameters": {
    "type": "object",
    "properties": {
      "currency": { "type": "string", "description": "3-letter currency code" }
    },
    "required": ["currency"]
  }
}

Paso 3: Utilice MCP cuando el agente deba descubrir herramientas

Qué hacer: utilizar MCP cuando un agente de IA de Pydantic debe conectarse a un servidor de herramientas remoto en lugar de depender solo de los envueltos locales. MCPToolset, con Streamable HTTP recomendado para servidores remotos y SSE tratado como obsoleto para nuevas implementaciones.

El servidor MCP FXMacroData canónico es:

{
  "servers": {
    "FXMacroData": {
      "type": "http",
      "url": "https://mcp.fxmacrodata.com"
    }
  }
}

En el código de IA de Pydantic, conecta el servidor MCP remoto como un conjunto de herramientas. Mantén secretos en tu almacén secreto de tiempo de ejecución siempre que sea posible; el formulario de parámetro de consulta a continuación es la forma de ejemplo público explícito.

from pydantic_ai import Agent
from pydantic_ai.mcp import MCPToolset

fxmd_toolset = MCPToolset(
    "https://mcp.fxmacrodata.com?api_key=YOUR_API_KEY"
)

mcp_agent = Agent(
    "openai:gpt-5-mini",
    toolsets=[fxmd_toolset],
    output_type=MacroBriefing,
)

result = await mcp_agent.run("Use FXMacroData tools for a USD briefing.")
print(result.output)

Los envases REST y MCP no son ideas competidoras. REST es mejor cuando su servicio posee todos los límites de solicitud. MCP es mejor quando un host o agente de ejecución compatible debe descubrir una superficie de herramienta FXMacroData curada.

Paso 4: Valida la salida antes de que nadie confíe en ella

Qué hacer: Pydantic AI admite la validación de salida, y los flujos de trabajo financieros deben usar ese paso para hacer cumplir la evidencia, las fechas y la divulgación de lagunas.

from pydantic_ai import ModelRetry

@agent.output_validator
def require_evidence(output: MacroBriefing) -> MacroBriefing:
    if not output.evidence_used:
        raise ModelRetry("Name the FXMacroData endpoint paths used.")
    if not output.key_values:
        raise ModelRetry("Include dated values or explain why unavailable.")
    if output.human_review_required is not True:
        raise ModelRetry("Keep human_review_required set to true.")
    return output

La validación no hace que un modelo sea un comerciante, sino que hace que la salida del modelo sea más fácil de rechazar antes de que llegue a una nota de investigación, cola de alertas, anotación del tablero o flujo de trabajo interno.

Paso 5: Añadir barreras de seguridad financieras

Pydantic AI te da una manera limpia de vincular llamadas de modelos, herramientas, dependencias y salida escrita.

• Sólo para lectura primero: exponer el calendario, los anuncios, el FX, el COT, las materias primas y los datos de la sesión antes de cualquier superficie similar a la escritura.
• Pruebas antes de la prosa: Requieren una llamada de FXMacroData antes de escribir sobre los eventos de macro actuales.
• Las pequeñas esquemas: Prefieren herramientas estrechas y un modelo de salida tipo en lugar de un agente general amplio.
• Divulgación de las lagunas: hacer que los resultados vacíos y los campos faltantes formen parte del objeto de salida final.
• Revisado en humanos: mantener la ejecución de operaciones, los cambios de cuenta y los cambios en el límite de riesgo fuera del primer agente.

Required briefing contract:
1. FXMacroData endpoint or MCP tool used
2. Currency, indicator, dates, and values
3. Prior and revised values where available
4. Interpretation separated from facts
5. Data gaps or stale-data warnings
6. Human review required

Preguntas frecuentes

¿Puede Pydantic AI usar FXMacroData?

Sí. Utilice envueltas REST directas, herramientas de función de IA de Pydantic, FXMacroData MCP, o una combinación. REST le da a su aplicación el mayor control sobre las credenciales y registro. MCP es útil cuando el agente debe descubrir herramienta de https://mcp.fxmacrodata.com- ¿ Qué ?

¿Debería Pydantic AI reemplazar una fuente de datos macro?

No. Pydantic AI coordina modelos, herramientas, dependencias y salida estructurada. FXMacroData debe seguir siendo la fuente de filas de macro, calendarios de lanzamiento, contexto de FX, COT, productos básicos, tiempo de sesión, marcas de tiempo y brechas de datos.

¿Debería usar REST o MCP con IA de Pydantic?

Utilice REST cuando su aplicación posee credenciales, validación, intentos de reutilización, política de caché y registros. Utilice MCP cuando un servidor de servidor o servicio Python compatible deba descubrir herramientas FXMacroData a través de un servidora estándar.

¿Cuál es la principal ventaja de la IA de Pydantic para los agentes financieros?

La principal ventaja es la salida y validación de tipos. Un agente financiero debe devolver un objeto comprobado con evidencia, valores, lagunas y estado de revisión en lugar de un párrafo no estructurado que es difícil de auditar.

Fuentes y referencias

• Documentación de los agentes de IA de Pydantic
• Documentación de las herramientas de función de IA de Pydantic
• Documentación de salida estructurada de IA de Pydantic
• Pydantic AI MCP es una aplicación de la tecnología de la inteligencia artificial.
• Documentación del cliente MCP de Pydantic AI
• Modelos y proveedores de IA de Pydantic
• Documentación de la API de FXMacroData
• Documentación de la MCP de FXMacroData
• Esquema de producción de FXMacroData y OpenAPI