Agents

Documentation Index

Fetch the complete documentation index at: https://docs.shingleai.com/llms.txt

Use this file to discover all available pages before exploring further.

ShingleAI has two kinds of AI worker: agents and automations. They look similar from a distance — both use LLMs, both can call tools, both can read your data and act on it — but they answer different questions, and using them interchangeably is the most common source of confusion for new users. Read this page, then read Automations. Together they give you a clear sense of which one to reach for.

​

Agents vs. Automations at a Glance

A useful intuition: an automation is a tireless junior employee waiting for the inbox to ping. An agent is a colleague you can ask things of. The two cooperate. An automation can invoke an agent as one of its steps when the work needs more nuance than rules can capture — for example, “when a new email arrives, ask the support agent to draft a reply.”

​

What is an Agent?

An agent is a configured persona that runs an LLM loop. When you create an agent you decide:

• Name and system prompt — who the agent is and how it should behave.
• Model — which LLM powers it.
• Tools it has access to — and at what permission level.
• Step budget — maxSteps caps how many tool calls a single response can make. The default is 5.
• LLM parameters — temperature, top-p, frequency/presence penalties, and so on, for power users.

When a person (or another workflow) sends the agent a message, it runs an agentic loop: read the message, choose a tool to call, get the result, choose another tool, until it’s done or it hits its step budget. Each agent runs inside its own Cloudflare Durable Object, which keeps the conversation state warm for the duration.

​

Tool Permissions

Tools are the only way an agent affects the world — read your contacts, send an email, create a task, search files. ShingleAI gives you granular control over each tool, with three levels: Sensible defaults are applied for you: read-style tools default to allow (an agent should be able to look things up without asking permission), write- and delete-style tools default to ask (anything that mutates state should pause for a human). You can override any of these per agent.

​

Conversations

Every chat with an agent is recorded as an agent conversation — a thread you can revisit, share, or audit later. Each conversation has:

• A status: active, completed, timeout, or error.
• A source: web (the dashboard chat UI), api, or mcp (a Model Context Protocol client like Claude Desktop or Cursor).
• The full transcript, including tool calls, tool results, and any approval decisions.

Conversations are how you scale review of AI work without watching every step in real time. You can browse the conversation history of any agent and see exactly what it did and why.

​

How an Agent Runs

The loop is bounded — maxSteps is a hard cap on tool calls per turn — and is interruptible. If a permission prompt comes back denied, or if you pause the conversation, the agent stops cleanly.

​

When to Use Which

Reach for an agent when:

• You want to ask follow-up questions in a conversation.
• The work needs judgement, not just rules — “summarise this account’s recent activity,” “draft a polite refund refusal.”
• You want a human in the loop on writes.

Reach for an automation when:

• The trigger is an event you can describe — “a new email arrives,” “a customer signs up.”
• You want it to run forever, untouched, until you tell it to stop.
• The behaviour is predictable enough that you don’t need to chat about it.

When in doubt: if you’d ever consider hitting “send” yourself before the action happens, you probably want an agent. If the action should always happen the moment the trigger fires, you probably want an automation.

​

Related Topics