What is an agent

An agent is a file that calls chatAgent(). Where a workflow is one run, an agent is one conversation: every message wakes it, and the thread is kept between messages.

import { chatAgent, model } from "@loops/sdk";
 
import { bookAppointment } from "./tools";
 
export const healthChatAgent = chatAgent({
  id: "health-chat",
  execute: async ({ submit, messages }) =>
    submit({
      messages,
      instructions: "You are the front desk for a small clinic.",
      tools: [bookAppointment],
      model: model("gpt-4o-mini"),
    }),
});

The parts

• id — the agent’s name.
• execute — runs once per message. It is one turn.
• messages — the thread so far, including the message that just arrived. Each one has a role of user or assistant, and content.
• submit — the model call for this turn. It returns the reply message, which is saved on the thread.
• instructions — the system prompt for the turn.
• tools — what the model may call during submit. A tool is made with defineTool. See Tools for an agent.
• model — which model answers. model("gpt-4o-mini") takes a model id, a <provider>/<model> id such as "openai/gpt-4o-mini", or a Workers AI id such as "@cf/meta/llama-3.1-8b-instruct".
• env — the loop’s variables and secrets, next to messages and submit.

A thread

One conversation is one thread. Every message and every reply is stored on it, so the next turn starts from the thread and not from scratch. A new thread does not see another one.

Values you keep in memory inside execute do not carry over to the next turn. Only the thread does. To remember something about a person across threads, save it with ctx.USER from a workflow.

Agents and workflows

An agent answers now. A workflow can wait, and it is where the built-in tools and bindings are. When the conversation needs a scan, a red-flag check, or a text message, the agent’s tool starts a workflow, tells the person what happens next, and the workflow does the work. See Calling a workflow.

Anything outside Loops sends a message with the chat endpoint. People can also reach the agent on WhatsApp and email.