LLM calls and agents

Use the smallest API that matches the job:

See Configure a model provider before you use a real provider. Use provider: "mock" in examples and tests that should run without credentials.

One model call#

import { LlmCallOptions } from "std/llm/options"

fn main(harness: Harness) {
  const options: LlmCallOptions = {
    provider: "mock",
    max_tokens: 128,
  }
  const response = harness.llm.call(
    "Translate 'Hello, world' to French.",
    "You are a concise translator.",
    options,
  )
  harness.stdio.println(response.text)
}

harness.llm.call returns a canonical response. Read text for the answer; read usage, outcome, tool_calls, and transcript when your program needs accounting or run information. See LLM calls for the full return shape, structured output, streaming, and errors.

An agent loop#

Use a loop when the model must choose actions across several turns. Build the options as an AgentSpec so harn check can catch misspelled options.

import { agent_loop } from "std/agent/loop"
import { AgentSpec } from "std/agent/options"

fn main(harness: Harness) {
  const options: AgentSpec = {
    provider: "mock",
    loop_until_done: true,
    max_iterations: 2,
  }
  const result = agent_loop(
    harness,
    "Answer this question in one sentence: why test a program?",
    "You are a concise teacher.",
    options,
  )
  harness.stdio.println(result.status)
  harness.stdio.println(result.text)
}

An agent result includes the visible text, terminal outcome, model usage, tool summary, and transcript. Only a natural terminal outcome proves that the agent completed its task. See Agent loops for tools, budgets, sessions, workers, and suspension.

Workflows and workers#

Use a workflow when the program has named stages, dependencies, joins, or verification steps. Use a worker when a parent must delegate independent or long-running work. These are orchestration choices; the model call remains the smallest unit inside them.

• Workflow runtime
• Delegated workers
• Typed tools
• Streaming and transcripts

Provider choice#

Harn resolves a provider from call options, project configuration, environment, or the model catalog. For reproducible programs, set the provider explicitly in the options and use a current model from harn models list.

The provider reference contains endpoint and capability details. The provider setup guide contains the shortest path from an API key to a verified call.