# Crear un agente

Diga qué debe hacer el <Term id="agent">agente</Term> y cuándo. La IA del [Studio](/docs/es/projects/studio) de su proyecto convierte sus palabras en pasos y código y guarda un **borrador**. Un borrador nunca se ejecuta solo, así que puede probarlo y cambiarlo con libertad.

## Antes de empezar [#antes-de-empezar]

- Un <Term id="project">proyecto</Term> que pueda editar. El agente usa el acceso a datos de ese proyecto.
- Datos al alcance del proyecto: una tabla en [Nexus](/docs/es/data/tables), una carpeta en el [Almacenamiento de objetos](/docs/es/data/object-storage) o una dirección web.
- Construir no requiere un administrador. Activarlo sí (consulte [Probar, activar y pausar](/docs/es/agents/go-live)).

## Describa un agente nuevo [#describa-un-agente-nuevo]

<ForEveryone>

<Steps>
<Step>
### Abra Agentes [#abra-agentes]
Vaya a <AppLink to="agents" /> y seleccione **Nuevo agente**. También puede abrir un proyecto y usar su pestaña **Agentes**.
</Step>
<Step>
### Elija el proyecto [#elija-el-proyecto]
Elija el **Proyecto**. Sus datos y su acceso vienen de allí.
</Step>
<Step>
### Diga qué debe hacer y cuándo [#diga-qué-debe-hacer-y-cuándo]
En **¿Qué debería hacer y cuándo?**, nombre los datos, qué hacer con cada elemento, dónde guardar el resultado y cuándo iniciarse. Por ejemplo:

> Todas las mañanas a las 7, lea las filas de ayer en sales.orders, haga que la IA marque cualquier pedido que parezca inusual con una razón de una línea, pregúnteme y luego guarde las marcas en sales.order_flags.

Seleccione **Pedir a la IA**.
</Step>
<Step>
### Deje que la IA construya el borrador [#deje-que-la-ia-construya-el-borrador]
La IA del Studio escribe los pasos y el código y guarda un borrador. Si el Studio no está en ejecución, la aplicación dice **En cola hasta que se abra el Studio**.
</Step>
<Step>
### Revise el borrador [#revise-el-borrador]
Abra el agente para ver sus pasos como un flujo y lo que lo inicia. Haga clic en un paso para ver su instrucción, consulta, tabla, reintentos y límite de tiempo.
</Step>
</Steps>

<Screenshot src="/docs/_media/demp-bakery-business-data-agent-flow-page.png" alt="Un borrador de agente nuevo con sus pasos como un flujo" />

</ForEveryone>

<ForDevelopers>

Un agente es un archivo YAML en `agents/<name>.yaml` dentro del proyecto, con su código Python en `agents/<name>/`. Esta es la plantilla **Resumen diario de una tabla**, tal como viene:

<Files>
<Folder name="agents" defaultOpen>
<File name="daily-summary.yaml" />
<Folder name="daily-summary" defaultOpen>
<File name="read_rows.py" />
</Folder>
</Folder>
</Files>

```yaml title="agents/daily-summary.yaml"
description: Summarise a table every morning
trigger:
  schedule: {at: "08:00"}
inputs:
  table: {type: string, default: my_table, description: The table to summarise}
steps:
  - {id: rows, kind: code, run: read_rows.py}
  - id: summary
    kind: ai
    needs: [rows]
    prompt: Summarise these rows for a busy manager in five short bullet points. Point out anything unusual.
result: summary
```

```python title="agents/daily-summary/read_rows.py"
from klarety import Nexus, step

table = step.inputs()["table"]
if not table.replace("_", "").replace(".", "").isalnum():
    raise ValueError(f"{table} is not a table name")
with Nexus.connect() as lakehouse:
    rows = lakehouse.sql(f"select * from {table} limit 200").rows
step.output([dict(row) for row in rows])
```

El `kind` de un paso es uno de `code`, `ai`, `think` (investiga en la web), `sql`, `write_table`, `approval` o `agent`. `needs` lista los pasos que espera, `for_each` lo ejecuta una vez por cada elemento que hizo un paso anterior, y `result` nombra el paso cuya salida es el resultado de la ejecución.

Revise el archivo y luego guárdelo como borrador desde la carpeta del proyecto. La [CLI](/docs/es/developers/cli) y la [referencia de agentes del SDK](/docs/es/developers/agents) cubren cada opción.

<Callout type="info" title="Inicie sesión primero">
  Fuera de un Studio, inicie sesión una vez con `klarety login <api-key>` o defina `KLARETY_API_KEY`. Consulte [Autenticación](/docs/es/developers/authentication).
</Callout>


<Tabs items={["CLI", "Python"]}>
<Tab value="CLI">
```bash
klarety agent check daily-summary --project PROJECT_ID
klarety agent save daily-summary --project PROJECT_ID
```
</Tab>
<Tab value="Python">
```python
from klarety import Nexus

nx = Nexus.connect()
print(nx.agents.check("PROJECT_ID", open("agents/daily-summary.yaml").read()))
version_id = nx.agents.save("PROJECT_ID", "daily-summary")
print(version_id)
```
</Tab>
</Tabs>

Dentro de un Studio puede omitir `--project`: la CLI usa el proyecto del Studio. Para que la IA del Studio construya el agente a partir de sus palabras, envíe una solicitud:

```python
nx.agents.ask_ai("PROJECT_ID", "Every hour, copy https://api.example.com/items into a table")
```

</ForDevelopers>

## Cambiar un agente [#cambiar-un-agente]

<ForEveryone>

Abra el agente, describa el cambio en **¿Qué debería cambiar?** y seleccione **Pedir este cambio a la IA**. Para cambiar una opción usted mismo, seleccione **Editar**, haga clic en el paso, cámbielo y seleccione **Guardar borrador**.

En un agente activo, los cambios quedan como borrador (**Activo, con cambios en borrador**) hasta que se active de nuevo; la versión activa sigue funcionando.

</ForEveryone>

<ForDevelopers>

Edite el YAML o el código y ejecute de nuevo `klarety agent save <name>`. Cada guardado es una nueva versión en borrador; la versión activa no cambia hasta que una persona active la nueva.

</ForDevelopers>

<Callout type="info" title="El Studio no necesita estar abierto">
  Si el Studio está detenido, su solicitud se conserva y la IA empieza cuando el Studio se abra de nuevo.
</Callout>

## Qué ve cuando funcionó [#qué-ve-cuando-funcionó]

El agente aparece en **Aún sin publicar**, marcado como **Borrador**, con **Inicia al activarse** en los inicios automáticos. Después, **Probar** ejecuta el borrador una vez, ahora.

## Escriba una buena descripción [#escriba-una-buena-descripción]

- **Nombre sus datos con exactitud**: la tabla, la carpeta o la dirección web.
- **Diga cuándo se inicia**: una hora y unos días, "cuando lleguen archivos a invoices/" o "solo cuando presione Ejecutar".
- **Diga a dónde va el resultado**: una tabla, un archivo o solo un resumen corto.
- **Pida una revisión antes de algo importante.** Decir "pregúntame antes de guardar" agrega un paso **Le pregunta primero**.

## Si algo sale mal [#si-algo-sale-mal]

- **"Aún no hay un proyecto que pueda editar"**: usted no edita ningún proyecto. Cree uno o pídaselo a su propietario.
- **La solicitud espera**: el Studio no está en ejecución. La IA empieza cuando el Studio se abra de nuevo.
- **`klarety agent check` informa un problema**: el YAML tiene un error y la respuesta dice cuál. Corrija el archivo y revíselo de nuevo.
- **"name the project with --project, or run this in its Studio"**: fuera de un Studio, pase `--project`.

## Siguientes pasos [#siguientes-pasos]

- [Plantillas](/docs/es/agents/templates)
- [Probar, activar y pausar](/docs/es/agents/go-live)
- [Ejecuciones y aprobaciones](/docs/es/agents/runs)