Skip to main content

Tools, agents, and managers

Choose the right unit of work: a single-capability tool, a conversational agent, a multi-agent manager — or no LLM at all, just a script.

The decision: you have a capability to build. Is it one deterministic action, one conversational assistant, or a team of assistants — and does it even need an LLM?

The systems​

  • Tools (autessa.tools.*) — a single capability. A tool is backed by a script, an LLM call, or a connector, takes typed inputs, and returns a result. Tools are the reusable verbs of the platform; triggers, scheduled events, and webhooks all invoke tools.
  • Agents (autessa.agents.*) — a conversational assistant with a persona, optional knowledge, and its own tools. Agents have a draft → publish lifecycle (autessa.agents.update, then autessa.agents.publish) and hold multi-turn conversations (autessa.agents.execute). Running an agent bills agent execution.
  • Managers (autessa.agenticManagers.*) — an orchestrator that runs a team of sub-agents on a task. Same draft → publish lifecycle. A manager conversation bills the configured number of sub-agents (the sub-agents do not bill separately) — see the metering-billing guide.

Decision rules​

  1. One deterministic action → a tool. If the work is "do X to these inputs" with no need for conversation, build a tool with autessa.tools.create and configure it with autessa.tools.update. Make it dynamic with arguments: any value that changes per run must be declared under the tool's arguments (or privateArguments for secrets), then referenced in the config with the @@{argumentName} placeholder — it is substituted at execution time (an AUTESSA_SCRIPT tool reads them with variables.get('name') instead). Declare each argument with its full shape — an object with description (string), isRequired (boolean), and argumentSchema (a JSON-schema object that MUST contain a type, e.g. { "type": "string" }). An argument written as just { description } with no argumentSchema cannot be rendered or edited in the tool UI and cannot run — set argumentSchema.type (use "string" when unsure). Then test it: call autessa.tools.execute with sample values and check the result, so you confirm every argument you referenced is declared and resolves. A mistyped @@{name} is left unsubstituted rather than erroring, so executing is the only reliable way to catch a missing argument. Iterate update → publish → execute until it's right before attaching it to an agent.
  2. No judgement needed → skip the LLM entirely; just script it. If plain code can do it, write an AutessaScript that calls the autessa.* SDK directly. Not every automation needs an agent; a script that queries a table and sends an email is cheaper and more predictable.
  3. A conversation with a user or a persona → an agent. If the work is open-ended dialog, needs to search over documents, or should feel like an assistant, build a SIMPLE agent with autessa.agents.create, publish it with autessa.agents.publish, and talk to it with autessa.agents.execute. SIMPLE is the agent type you build — give it document search by attaching a semantic-query tool over a basic vectorized table (see the grounding-agent-on-documents guide). Other agent types are out of scope; don't reach for them. An agent uses only the tools attached to it. Building a tool does not connect it to any agent — you attach it by adding the tool to the agent's tools array via autessa.agents.update, then autessa.agents.publish. So the full flow to give an agent a capability is: build + test the tool (tools.create → tools.update → tools.publish → tools.execute to verify), then attach it (agents.get → add to tools → agents.update → agents.publish).
  4. A task too big for one agent → a manager. If the job needs several specialists coordinated (research, then draft, then review), build a manager with autessa.agenticManagers.create. Budget for it deliberately: it bills its configured sub-agent count.

Worked examples​

A. Format a phone number. Pure logic — no LLM. Write a script, or publish it once as a tool with autessa.tools.create so a trigger can reuse it.

B. A support assistant over your documents. Create a SIMPLE agent with autessa.agents.create, attach a semantic-query tool over a basic AutessaDB table with a vectorized column (build it per the grounding-agent-on-documents guide), autessa.agents.publish it, then serve chats with autessa.agents.execute.

C. Draft-and-review a report. A manager (autessa.agenticManagers.create) coordinating a writer and a reviewer sub-agent produces a better result than one agent — at the cost of its configured sub-agent count per conversation.

See also​

  • scripting-model — how a plain AutessaScript runs when you skip the LLM.
  • metering-billing — what agent and manager execution costs.
  • automations — the triggers/events/webhooks that invoke tools and agents.