> For the complete documentation index, see [llms.txt](https://saptiva.gitbook.io/saptiva-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://saptiva.gitbook.io/saptiva-docs/saptiva-agents/introduccion.md).

# Introducción

### 🤖 Saptiva Agents

[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/) [![PyPI version](https://img.shields.io/pypi/v/saptiva-agents.svg)](https://pypi.org/project/saptiva-agents/) [![License](https://img.shields.io/github/license/saptiva/saptiva-agents)](https://github.com/saptiva-ai/saptiva-agents/blob/main/LICENSE) [![Documentation](https://img.shields.io/badge/docs-online-blue)](https://app.gitbook.com/o/YD7tmPjNuCJPBtMoeymU/s/1Xeu6KDnv2A0dUxoQDDU/saptiva-agents/)

**Saptiva-Agents** es un potente framework para construir aplicaciones de IA multiagente que pueden actuar de forma autónoma o colaborar con humanos.

**Saptiva-Agents** hace uso de nuestra [**API**](/saptiva-docs/basicos/api-reference.md)**.**

***

### ⚙️ Instalación

**Saptiva-Agents** requiere **Python 3.10 o superior**. Para instalar desde [**PyPI**](https://pypi.org/project/saptiva-agents/):

```bash
pip install -U saptiva-agents
```

***

### 🚀 Inicio rápido

### 👋 Hola, Mundo

Crea un agente asistente usando  `Saptiva Legacy` con **Saptiva-Agents**:

```python
import asyncio

from saptiva_agents import SAPTIVA_LEGACY
from saptiva_agents.base import SaptivaAIChatCompletionClient
from saptiva_agents.agents import AssistantAgent

async def main() -> None:
    model_client = SaptivaAIChatCompletionClient(
        model=SAPTIVA_LEGACY, 
        api_key="TU_SAPTIVA_API_KEY"
    )
    agent = AssistantAgent("assistant", model_client=model_client)
    response = await agent.run(task="Di '¡Hola Mundo!'")
    print(response.messages[1].content)
    
    await model_client.close()

asyncio.run(main())
```

```python
python hello_world.py
```

***

### 🌐 Equipo de Agentes para Navegación Web

Crea un equipo de agentes con navegador usando Playwright:

```python
# pip install saptiva-agents
# playwright install --with-deps chromium

import asyncio

from saptiva_agents import SAPTIVA_LEGACY
from saptiva_agents.agents import UserProxyAgent
from saptiva_agents.base import SaptivaAIChatCompletionClient
from saptiva_agents.conditions import TextMentionTermination
from saptiva_agents.teams import RoundRobinGroupChat
from saptiva_agents.web_surfer import MultimodalWebSurfer
from saptiva_agents.ui import Console

async def main() -> None:
    model_client = SaptivaAIChatCompletionClient(
        model=SAPTIVA_LEGACY, 
        api_key="TU_SAPTIVA_API_KEY"
    )
    web_surfer = MultimodalWebSurfer(
        "web_surfer", 
        model_client, 
        headless=False, 
        animate_actions=True, 
        start_page="https://www.google.com"
    )
    user_proxy = UserProxyAgent("user_proxy")
    termination = TextMentionTermination("salir", sources=["user_proxy"])
    team = RoundRobinGroupChat([web_surfer, user_proxy], termination_condition=termination, max_turns=3)

    try:
        await Console(team.run_stream(task="Navega a saptiva.com y consigue información sobre Saptiva AI."))
        # Al escribir el texto de finalización en la consola (salir), el script se detendrá
    finally:
        await web_surfer.close()
        await model_client.close()

asyncio.run(main())
```

```bash
python web_surfer.py
```

***

### 🎭 Orquestación Multiagente

Puedes usar **`AgentTool`** para crear una configuración básica de orquestación multiagente.

```python
import asyncio

from saptiva_agents.tools import AgentTool
from saptiva_agents.agents import AssistantAgent
from saptiva_agents.ui import Console
from saptiva_agents.base import SaptivaAIChatCompletionClient


async def main() -> None:
    model_client = SaptivaAIChatCompletionClient(
        model="Saptiva Legacy", 
        api_key="TU_SAPTIVA_API_KEY"
    )
    math_agent = AssistantAgent(
        "math_expert",
        model_client=model_client,
        system_message="Eres un experto en matemáticas.",
        description="Un asistente experto en matemáticas.",
        model_client_stream=True,
    )
    math_agent_tool = AgentTool(math_agent, return_value_as_last_message=True)

    chemistry_agent = AssistantAgent(
        "chemistry_expert",
        model_client=model_client,
        system_message="Eres un experto en química.",
        description="Un asistente experto en química.",
        model_client_stream=True,
    )
    chemistry_agent_tool = AgentTool(chemistry_agent, return_value_as_last_message=True)

    agent = AssistantAgent(
        "assistant",
        system_message="Eres un asistente general. Usa las herramientas de expertos cuando sea necesario.",
        model_client=model_client,
        model_client_stream=True,
        tools=[math_agent_tool, chemistry_agent_tool],
        max_tool_iterations=10,
    )

    await Console(agent.run_stream(task="¿Cuál es la integral de x^2?"))
    await Console(agent.run_stream(task="¿Cuál es el peso molecular del agua?"))

asyncio.run(main())
```

***

### 📚 Modelos Disponibles

**Saptiva-Agents** soporta una variedad de modelos para tareas tanto de texto como multi-modales. 

#### 🧠 Modelos de Texto (tareas básicas)

| Nombre          | Modelo Base     | Mejor para                        | Caso de Uso                                                         |
| --------------- | --------------- | --------------------------------- | ------------------------------------------------------------------- |
| `Saptiva Ops`   | gpt-oss:20b     | Tareas que implican razonamiento. | Agentes autónomos, RAG                                              |
| `Saptiva Guard` | llama-guard3:8b | Moderación y cumplimiento         | Protección de contenido, validación de incumplimiento legal en LLMs |

En caso de requerir implementación de herramientas (tools) te recomendamos usar los siguientes modelos que soportan dicha caracteristica:

#### 🧠 Modelos de Texto (Tools)

| Nombre           | Modelo Base  | Mejor para                             | Caso de Uso                                   |
| ---------------- | ------------ | -------------------------------------- | --------------------------------------------- |
| `Saptiva Cortex` | qwen3-tk:30b | Tareas de razonamiento                 | Agentes con lógica, comprensión profunda      |
| `Saptiva Turbo`  | qwen3-it:30b | Casos complejos con tools y SDK        | Agentes autónomos, RAG, websearch             |
| `Saptiva Legacy` | llama3.3:70b | Compatibilidad con herramientas legacy | SDK avanzado, pruebas, compatibilidad técnica |

#### 🖼️ Modelo Multimodal

| Nombre        | Modelo Base   | Mejor para                                                   | Caso de Uso                                    |
| ------------- | ------------- | ------------------------------------------------------------ | ---------------------------------------------- |
| `Saptiva OCR` | `Saptiva OCR` | Extracción inteligente de texto e interpretación de imágenes | OCR, estructuración de documentos, VLM, visión |

{% hint style="info" %}
Nota:

**Saptiva Agents** no soporta **embeddigs**, por lo tanto, el modelo `Saptiva Embed` no está disponible.
{% endhint %}

> 🔗 [Ver lista completa de modelos disponibles en **Saptiva**](https://saptiva.gitbook.io/saptiva-docs/basicos/modelos-disponibles)

***

### 🧰 Custom Tools

Junto a la **SDK** viene un grupo de tools pre-determinadas con funcionalidades que puedes adherir en la fase de inicialización de tus agentes, estas tools dan acceso a funcionalidades tales como extracción de documentos, consultas **CURP**, **CFDI** y demás.\
\
Haz clic en el siguiente link para más información:

{% content-ref url="/pages/wTD5jfS6vdGVRnVVaZYQ" %}
[Custom Tools](/saptiva-docs/saptiva-agents/custom-tools.md)
{% endcontent-ref %}

{% hint style="info" %}
Nota:

La lista de tools pre-determinadas está disponible a partir de la versión **0.1.3** de nuestro **SDK.**
{% endhint %}

***

### 📄 Licencia

Este proyecto está licenciado bajo la [Licencia MIT](https://github.com/saptiva-ai/saptiva-agents/blob/main/LICENSE).

***

### 🌐 Enlaces

* 🔗 [Documentación Oficial](https://saptiva.gitbook.io/saptiva-docs/)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://saptiva.gitbook.io/saptiva-docs/saptiva-agents/introduccion.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.