Klarety

Agents and runs

Save, test, start, follow, approve and stop agent runs from Python.

For devs

An is a saved set of steps that works on your data, on a schedule or when something happens. Every agent belongs to a . New to agents? Start with Create an agent.

Before you start

  • You have the project ID of the project the agent lives in, and you can edit that project.
  • Taking an agent live needs a owner or admin, because a live agent spends .
  • Every example assumes nexus = Nexus.connect().

Find agents

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

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

Save and test a draft

An agent is a file agents/<name>.yaml with its Python code in agents/<name>/, inside your project's code. save() stores both from a local folder as a draft:

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) checks the YAML text without saving it. A draft never runs on its own; start(..., draft=True) runs it once.

Take it live

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

A person decides in the app. An owner or admin can publish directly with nexus.agents.publish(PROJECT, "daily-summary", version_id); anyone else is refused. unpublish() takes it offline, and publish() with an earlier version_id brings that version back. nexus.agents.version(project_id, version_id) shows a saved version.

Start a run and follow it

Each reports its state and steps:

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"])

A run ends as done, failed, declined or stopped. Each step has its own state: waiting, running, asking, done, failed, declined, stopped or skipped, among others.

Answer an approval step

A step in the asking state waits for a person to say yes:

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

yes=True continues the run. yes=False stops it at that step.

Read what a run produced

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))

For a step that runs once per item, pass item= to outputs(), output() and log() to read one item.

List runs, stop and rerun

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() starts a new run from one step, reusing earlier steps' output. To page from another process, use runs_page() and pass its next back as after.

Delete an agent

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

The agent is paused and removed from the list. Its runs stay on record.

What can go wrong

ExceptionCauseWhat to do
KlaretyError: agents/<name>.yaml does not existsave() could not find the file under root.Run from the project's folder or pass root=.
RefusedErrorYou cannot edit the project, or you are not an admin and tried to publish().Use ask_to_publish(), or ask for access.
NotFoundErrorNo such project, agent or run.Check the IDs.
InsufficientCreditsErrorThe workspace cannot pay for the run.Add credits.

Next steps

On this page

Before you startFind agentsSave and test a draftTake it liveStart a run and follow itAnswer an approval stepRead what a run producedList runs, stop and rerunDelete an agentWhat can go wrongNext steps