Results, streaming, and errors

Hosted operations return one normalized envelope even when providers use different response shapes. Application code can record model and usage metadata without reaching into an OpenAI- or Anthropic-specific object.

Synchronous result

type RunResult = {
  output: unknown;
  state: Record<string, unknown>;
  runId: string;
  traceId?: string;
  sessionId?: string;
  status: "completed";
  requestedAgentVersion?: string;
  resolvedAgentVersion?: string;
  provider?: string;
  model: string;
  usage: {
    inputTokens: number;
    outputTokens: number;
    totalTokens: number;
  };
  finishReason?: string;
  responseId?: string;
  warnings?: string[];
  retention?: {
    mode?: "none" | "result" | "session";
    ttlSeconds?: number;
    artifactTtlSeconds?: number;
  };
};

Python exposes the same fields with snake_case attributes: result.run_id, result.trace_id, result.session_id, result.requested_agent_version, result.resolved_agent_version, result.finish_reason, and result.response_id.

runId exists for correlation even when retention.mode is none; it does not imply a durable record. traceId and sessionId are present only when the retention policy creates those records.

Structured output failures

Canonical output schemas are passed to providers that support structured generation and are also validated by Agntz. A response that cannot satisfy the declared contract fails with a structured schema error instead of silently returning malformed application data.

Manifest validation errors include JSON Pointer paths. Client errors preserve the worker's stable code, HTTP status, message, and request details when available.

Streaming

agents.stream uses Server-Sent Events and yields a start event followed by operation events and exactly one terminal complete or error event.

for await (const event of client.agents.stream({
  agentId: "support",
  input: "Explain my invoice",
  retention: { mode: "session" },
})) {
  if (event.type === "start") {
    console.log(event.kind, event.runId, event.traceId, event.sessionId);
  }
  if (event.type === "text-delta") process.stdout.write(event.text);
  if (event.type === "reply") console.log("reply", event.text);
  if (event.type === "complete") console.log(event.output);
  if (event.type === "error") console.error(event.error);
}

Breaking out of the iterator closes the HTTP response. Pass an AbortSignal in TypeScript or close the Python iterator/client when the calling job is cancelled.

Durable asynchronous runs

Use agents.start or runs.start when work must continue independently of the request connection.

const run = await client.agents.start({
  agentId: "large-enrichment",
  input: batch,
  retention: { mode: "result", ttlSeconds: 86_400 },
});

const current = await client.runs.get(run.id);
await client.runs.cancel(run.id);

Durable starts reject retention.mode: none. Run streams can reconnect with a sequence cursor where supported.

Error classes

import {
  AgntzError,
  AuthenticationError,
  NotFoundError,
  StreamError,
} from "@agntz/client";

try {
  await client.agents.run({ agentId: "missing", input: {} });
} catch (error) {
  if (error instanceof AgntzError) {
    console.error(error.code, error.status, error.message);
  }
}

from agntz import AgntzError, AuthenticationError, NotFoundError

try:
    client.agents.run(agent_id="missing", input={})
except AgntzError as error:
    print(error.code, error.status, str(error))

Common error families include authentication, unknown agents or artifacts, manifest and input schema validation, forbidden retention changes, cancelled runs, outbound URL rejection, provider failures, and rate limits. Treat code as the machine-readable discriminator and message as diagnostic text.

Provider warnings and finish reasons are data, not exceptions. Store them with the resolved agent version when they matter to quality or billing analysis.