Your first agent

Give an agent a brief, a tool, and a source, then read the trace it leaves.

Table of Contents

Describe the outcome
Run it
Read the trace

This assumes you have finished the quickstart and connected at least one source.

Describe the outcome

An agent's brief is prose, not configuration. Say who asks it things, what a good answer looks like, and what it must never do.

const agent = await frontal.agents.create({
  name: "Invoice triage",
  brief: "Answer questions about unpaid invoices. Never promise a payment date.",
  tools: ["entities.read"],
});

Run it

const run = await frontal.runs.create({
  agentId: agent.object?.id ?? "",
  input: "Which invoices are more than 30 days overdue?",
});

Read the trace

Every run records what the agent read, which tools it called, and why it stopped.

const trace = await frontal.runs.getTrace({ runId: run.object?.id ?? "" });

Read the trace before you edit the brief. An agent that never read the relevant record has a context problem, and no amount of instruction will fix it. Observability covers what a trace holds.

Updated Aug 28, 2026