# Agentes y ejecuciones

Un <Term id="agent">agente</Term> es un conjunto guardado de pasos que trabaja con sus datos, según un horario o cuando algo ocurre. Cada agente pertenece a un <Term id="project">proyecto</Term>. ¿Es nuevo en agentes? Empiece por [Crear un agente](/docs/es/agents/create-an-agent).

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

- Tiene el **ID del proyecto** donde vive el agente, y puede editar ese proyecto.
- Poner un agente en vivo requiere un Propietario o Administrador del <Term id="workspace">espacio de trabajo</Term>, porque un agente en vivo gasta <Term id="credits">créditos</Term>.
- Todos los ejemplos suponen `nexus = Nexus.connect()`.

## Encuentre agentes [#encuentre-agentes]

```python
for agent in nexus.agents.list(project_id):
    print(agent)

for agent in nexus.agents.list_all():   # every project you can open
    print(agent)
```

## Guarde y pruebe un borrador [#guarde-y-pruebe-un-borrador]

Un agente es un archivo `agents/<name>.yaml` con su código Python en `agents/<name>/`, dentro del código de su proyecto. `save()` guarda ambos desde una carpeta local como borrador:

```python title="test_agent.py"
from pathlib import Path

from klarety import KlaretyError, Nexus

PROJECT = "your-project-id"

with Nexus.connect() as nexus:
    try:
        version_id = nexus.agents.save(PROJECT, "daily-summary", root=Path("."))
        run_id = nexus.agents.start(PROJECT, "daily-summary", draft=True, inputs={"days": 1})
    except KlaretyError as failed:
        raise SystemExit(f"Could not test the agent: {failed}")
    print("Draft", version_id, "running as", run_id)
```

`nexus.agents.check(project_id, text)` revisa el texto YAML sin guardarlo. Un borrador nunca se ejecuta solo; `start(..., draft=True)` lo ejecuta una vez.

## Póngalo en vivo [#póngalo-en-vivo]

```python
nexus.agents.ask_to_publish(PROJECT, "daily-summary", version_id)
```

Una persona decide en la app. Un Propietario o Administrador puede publicar directamente con `nexus.agents.publish(PROJECT, "daily-summary", version_id)`; cualquier otra persona es rechazada. `unpublish()` lo saca de línea, y `publish()` con un `version_id` anterior trae de vuelta esa versión. `nexus.agents.version(project_id, version_id)` muestra una versión guardada.

## Inicie una ejecución y sígala [#inicie-una-ejecución-y-sígala]

Cada <Term id="run">ejecución</Term> informa su estado y sus pasos:

```python title="run_and_wait.py"
import time

from klarety import Nexus

PROJECT = "your-project-id"

with Nexus.connect() as nexus:
    run_id = nexus.agents.start(PROJECT, "daily-summary")
    run = nexus.agents.run(PROJECT, run_id)
    while run["state"] == "running":
        time.sleep(10)
        run = nexus.agents.run(PROJECT, run_id)

    print(run["state"], run["reason"], run["credits"], "credits")
    for step in run["steps"]:
        print(step["id"], step["state"], step["reason"])
```

Una ejecución termina como `done`, `failed`, `declined` o `stopped`. Cada paso tiene su propio estado: `waiting`, `running`, `asking`, `done`, `failed`, `declined`, `stopped` o `skipped`, entre otros.

## Responda un paso de aprobación [#responda-un-paso-de-aprobación]

Un paso en estado `asking` espera a que una persona diga que sí:

```python
for step in run["steps"]:
    if step["state"] == "asking":
        nexus.agents.answer(PROJECT, run_id, step["id"], yes=True)
```

`yes=True` continúa la ejecución. `yes=False` la detiene en ese paso.

## Lea lo que produjo una ejecución [#lea-lo-que-produjo-una-ejecución]

```python
result = nexus.agents.result(PROJECT, run_id)
print(result["value"])         # up to 1 MiB
print(result["files"])         # files the run left

names = nexus.agents.outputs(PROJECT, run_id, step_id)
data = nexus.agents.output(PROJECT, run_id, step_id, names[0])   # bytes
print(nexus.agents.log(PROJECT, run_id, step_id))
```

Para un paso que se ejecuta una vez por elemento, pase `item=` a `outputs()`, `output()` y `log()` para leer un elemento.

## Liste ejecuciones, detenga y vuelva a ejecutar [#liste-ejecuciones-detenga-y-vuelva-a-ejecutar]

```python
for one in nexus.agents.runs(PROJECT, agent="daily-summary"):   # newest first, page by page
    print(one["run_id"], one["state"])

nexus.agents.stop(PROJECT, run_id)
new_run = nexus.agents.rerun(PROJECT, run_id, from_step="summarise")
print(nexus.agents.stats(PROJECT, days=7))   # runs per day: count, outcomes, cost
```

`rerun()` inicia una ejecución nueva desde un paso, reutilizando lo que produjeron los anteriores. Para paginar desde otro proceso, use `runs_page()` y pase su `next` como `after`.

## Elimine un agente [#elimine-un-agente]

```python
nexus.agents.delete(PROJECT, "daily-summary")
```

El agente se pausa y sale de la lista. Sus ejecuciones quedan registradas.

## Qué puede salir mal [#qué-puede-salir-mal]

| Excepción | Causa | Qué hacer |
| --- | --- | --- |
| `KlaretyError: agents/<name>.yaml does not exist` | `save()` no encontró el archivo bajo `root`. | Ejecute desde la carpeta del proyecto o pase `root=`. |
| `RefusedError` | No puede editar el proyecto, o no es administrador e intentó `publish()`. | Use `ask_to_publish()`, o pida acceso. |
| `NotFoundError` | No existe ese proyecto, agente o ejecución. | Revise los IDs. |
| `InsufficientCreditsError` | El espacio de trabajo no puede pagar la ejecución. | Agregue créditos. |

## Próximos pasos [#próximos-pasos]

- [Probar, poner en vivo y pausar](/docs/es/agents/go-live) para los mismos pasos en la app.
- [CLI](/docs/es/developers/cli) para los comandos `klarety agent`.
- [Trabajos y trabajos por lotes](/docs/es/developers/jobs) para trabajo en segundo plano sin un agente.