Content, artifacts, and retention

Hosted runs accept structured input and an independent ordered content message. Use input for template variables and application data; use content for the exact text, image, and audio parts sent to the operation.

Content blocks

URL blocks can include headers. The worker applies its outbound URL policy before downloading remote media. Do not place durable credentials in a manifest or content block when an uploaded artifact is sufficient.

const result = await client.agents.run({
  agentId: "extract-recipe",
  input: { sourceId: "video_123" },
  content: [
    { type: "text", text: "Extract the recipe shown in these frames." },
    {
      type: "image",
      file: { path: "./frames/001.png", mediaType: "image/png" },
      detail: "high",
    },
    {
      type: "image",
      url: "https://cdn.example.com/frame-002.jpg",
      detail: "low",
    },
  ],
  retention: { mode: "result", artifactTtlSeconds: 3_600 },
});

Node clients accept Blob, ArrayBuffer, Uint8Array, or a { path, mediaType, filename } object. Python clients accept pathlib.Path, path strings, bytes, and file-like objects. Local files are uploaded before the run and replaced with tenant-scoped artifact ids; local paths never appear on the wire.

Explicit artifact management

Use the artifact resource when several runs share the same media, when upload and execution happen in different jobs, or when you need to download generated images.

const artifact = await client.artifacts.upload({
  file: { path: "./narration.mp3", mediaType: "audio/mpeg" },
  purpose: "input",
  expiresInSeconds: 3_600,
});

const metadata = await client.artifacts.get(artifact.id);
const audio = await client.artifacts.download(artifact.id); // Blob

await client.agents.run({
  agentId: "social-transcription",
  content: [{ type: "audio", artifactId: artifact.id }],
  retention: { mode: "none" },
});

await client.artifacts.delete(artifact.id);

Artifact metadata includes the owner, purpose, media type, byte size, SHA-256 digest, creation and expiry times, status, and a short-lived signed download URL when the deployment provides one. Artifact ids are owner-scoped; one tenant cannot read another tenant's object even if it learns the id.

Uploads are limited to 50 MiB. Explicit and automatic input uploads accept lifetimes from 60 seconds through 7 days. Generated image artifacts can use the run's artifactTtlSeconds, from 60 seconds through one year.

Retention modes

Retention is independent from the provider's own data controls.

retention:
  mode: result
  ttlSeconds: 86400
  artifactTtlSeconds: 3600

A manifest can set the default. Callers may tighten it but cannot loosen it: none is stricter than result, which is stricter than session. ttlSeconds and artifactTtlSeconds must be integers from 60 through 31,536,000 seconds.

none is supported only for synchronous agents.run calls because an asynchronous run needs a durable record for status, cancellation, and reconnection. Use result with agents.start or runs.start when you want the smallest durable record.

With none or result, the returned sessionId and traceId are absent by design. Application code must treat them as optional.

Self-hosted artifact storage

S3 mode supports AWS S3 and compatible endpoints. Configure bucket lifecycle rules as a deletion backstop; Agntz metadata and object expiry remain tenant-scoped. See Self-host in production for the complete environment reference.