AeontelAeontel Docs

Runs hooks

React hooks for runs — list, get, cancel, plus the high-level {@link useExecuteRun} hook for executing any runnable entity (agent, swarm, workflow) and tracking its status.

Usage

TSX
import Aeontel from "@aeontel/sdk";
import { AeontelProvider, useListRuns } from "@aeontel/react";

const client = new Aeontel(import.meta.env.VITE_AEONTEL_API_KEY);

function App() {
  return (
    <AeontelProvider client={client}>
      <RunsList workspaceId="wsp_abc123" />
    </AeontelProvider>
  );
}

function RunsList({ workspaceId }: { workspaceId: string }) {
  const { data, isLoading } = useListRuns({ workspace_id: workspaceId });
  if (isLoading) return <p>Loading…</p>;
  return (
    <ul>
      {data?.data.map((r) => (
        <li key={r.id}>{r.status}</li>
      ))}
    </ul>
  );
}

Hooks

useCancelRun composite

Cancel a running run. Auto-invalidates run queries on success.

TypeScript
useCancelRun(options?: MutationOpts<Run, string>)

Types: Run

TypeScript
const cancel = useCancelRun();
cancel.mutate("run_abc123");

useExecuteRun composite

Execute any runnable entity (agent, swarm, workflow) and track its status. Detects entity type from the ID prefix and routes to the correct API endpoint.

Status lifecycle: idle -> pending -> running -> completed | failed. Polls the run status automatically when poll is true (default).

TypeScript
useExecuteRun<TInput extends Record<string, unknown> = Record<string, unknown>, TOutput = unknown>(id: string, options: UseRunOptions = {})
TypeScript
const { execute, status, output, isRunning } = useExecuteRun("agt_abc123");
return (
  <>
    <button disabled={isRunning} onClick={() => execute({ prompt: "Hi" })}>Run</button>
    <div>{status}</div>
    {output && <pre>{JSON.stringify(output)}</pre>}
  </>
);

useListRuns query

Fetch paginated list of runs. Supports workspace_id, status filters.

TypeScript
useListRuns(params?: Omit<ListRunsParams, | > & { filter?: RunFilter; orderBy?: RunOrderBy[]; } & RunShorthands, options?: QueryOpts<Page<Run>>)

Types: ListRunsParams · RunFilter · RunOrderBy · RunShorthands · Page · Run

TypeScript
const { data } = useListRuns({ workspace_id: "wsp_abc123", status: "running" });

useRetrieveRun query

Fetch a single run by ID.

TypeScript
useRetrieveRun(id: string, options?: QueryOpts<Run>)

Types: Run

TypeScript
const { data: run } = useRetrieveRun("run_abc123");