Marco paso a paso: cómo construir agentes de IA desde cero

🧭 Nota sobre el Stack Tecnológico

Este marco es agnóstico al proveedor de LLM. Puedes implementarlo con Claude (Anthropic), GPT-4o (OpenAI), Gemini (Google) o modelos open-weight como Llama 3.3 o GLM-5.2. Lo que cambia es la API; la arquitectura permanece igual.

▸ Python · Pydantic AI Definición de esquema de entrada/salida

from pydantic_ai import Agent
from pydantic import BaseModel
from typing import List

class ResearchInput(BaseModel):
    query: str
    max_sources: int = 5
    language: str = "es"

class ResearchOutput(BaseModel):
    summary: str
    key_points: List[str]
    sources: List[str]
    confidence_score: float

agent = Agent(
    model="claude-sonnet-4-5",
    result_type=ResearchOutput,
    system_prompt="Eres un investigador experto. Devuelve resultados estructurados."
)

▸ Python · LangChain Registro de herramientas con @tool

from langchain.tools import tool
from langchain_community.tools.tavily_search import TavilySearchResults

@tool
def search_web(query: str) -> str:
    search = TavilySearchResults(max_results=5)
    return str(search.invoke(query))

@tool
def execute_python(code: str) -> str:
    import subprocess
    result = subprocess.run(["python", "-c", code],
                           capture_output=True, text=True, timeout=30)
    return result.stdout or result.stderr

tools = [search_web, execute_python]

▸ Python · CrewAI Equipo de agentes especializados

from crewai import Agent, Task, Crew

planner = Agent(
    role="Planificador Estratégico",
    goal="Descomponer el objetivo en un plan ejecutable",
    backstory="Director de proyectos senior con metodología OKR",
    verbose=True, allow_delegation=True
)

researcher = Agent(
    role="Investigador de Mercado",
    goal="Encontrar datos precisos y fuentes verificables",
    backstory="Analista con acceso a datos en tiempo real",
    tools=[search_web], verbose=True
)

writer = Agent(
    role="Redactor Ejecutivo",
    goal="Transformar datos en narrativa clara y accionable",
    backstory="Escritor técnico con experiencia en reportes C-Suite",
    verbose=True
)

crew = Crew(agents=[planner, researcher, writer], verbose=True)

▸ Python · LangChain + Chroma Pipeline RAG semántico

from langchain_community.vectorstores import Chroma
from langchain_openai import OpenAIEmbeddings
from langchain.chains import RetrievalQA

embeddings = OpenAIEmbeddings()
vectorstore = Chroma.from_documents(
    documents=corporate_docs,
    embedding=embeddings,
    persist_directory="./chroma_db"
)

retriever = vectorstore.as_retriever(
    search_type="similarity",
    search_kwargs={"k": 5}
)

rag_chain = RetrievalQA.from_chain_type(
    llm=llm, retriever=retriever, return_source_documents=True
)

▸ Python · FastAPI Endpoint REST para invocar el agente

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI(title="Research Agent API", version="1.0")

class AgentRequest(BaseModel):
    query: str
    max_sources: int = 5

@app.post("/research", response_model=ResearchOutput)
async def run_research(request: AgentRequest):
    result = await agent.run(request.query)
    return result.data

# uvicorn main:app --host 0.0.0.0 --port 8000 --reload