How agents work

Audience

Anyone using BOS who wants to get more out of the chat panel.

Status

Stable — agents are in production, used daily by every BOS user.

A BOS agent is an AI assistant with a small, specialised set of tools. You ask a question in plain language; the agent decides which tools to call, executes them against your tenant data, and gives you the answer based on what it found.

The flow

You type: "Why is cash lower than last week?"
   │
   ▼
The Finance agent reads your question
   │
   ▼
It decides: I need the cash balance for two dates.
   │
   ▼
Tool call 1: GetBankBalance(date="last_week")
Tool call 2: GetBankBalance(date="today")
   │
   ▼
Each tool runs against your tenant, returns a number
   │
   ▼
The agent reasons: "Cash today is X, last week was Y. The difference
is Z, mostly explained by these recent transactions: …"
   │
   ▼
The answer streams into the chat panel, token by token.

Every tool call is visible. While the agent is thinking, you see a small "🔧 GetBankBalance(date=last_week)" bubble appear above the text answer. Click it to see what the tool returned.

The four agents

Each agent specialises in a domain:

Agent	Tools live	Sample questions
Finance	6	"What's my cashflow this month?", "Which invoices are overdue?"
Warehouse	4	"Which products are low?", "What pickings are pending?"
Marketing	4	"Pipeline by stage?", "Best-performing campaign last month?"
Sales	4	"Pipeline value?", "Top customers this quarter?"

The Chat panel shows tabs at the top — one per agent. Click a tab to switch agents. Your conversation with each agent is independent (the Finance agent does not see what you asked the Sales agent).

Why specialised agents

Most "AI assistants" try to do everything. PLANA Pulse takes a different approach: each agent has narrow scope and only the tools it needs.

Two benefits:

1. The agent picks the right tool. With 4 tools to choose from, the agent gets it right ~99% of the time. With 50 tools, mistakes compound.
2. Audit is meaningful. When you review the Execution log later, "Finance agent called GetGLBalance" tells you the workflow at a glance — the data domain and the action are tied to the agent.

If you ask the Sales agent about cashflow, it will tell you to switch to the Finance agent. Each agent knows its boundary.

What a tool actually does

A tool is a small function with a typed signature:

GetBankBalance(journal_id: int, date: str) -> {"balance": float, "currency": str}

When the agent decides to call this tool, the runtime:

1. Validates the arguments against the schema
2. Authenticates to your tenant Odoo as a read-only service user
3. Issues an ORM query (account.journal + account.move.line)
4. Returns the result to the agent
5. Logs the call to your Execution log

The tool is read-only for now (Shadow Mode — see Safety and limits). Tools that will write back to your tenant Odoo are coming; when they do, you opt in per-agent and per-tool.

What the agent CANNOT see

• Your competitor's data — agents are scoped to one workspace. Always your own data, never anyone else's.
• Fields the underlying tool didn't fetch — if the tool only reads invoice totals, the agent never sees individual line items even if it asks.
• Data outside your tenant — tools read from your PLANA Business Cloud tenant. They do not reach into Stripe, your bank, or your email.

If an agent says "I don't have a tool for that", it is being accurate — it cannot fabricate data to fill a gap.

Streaming

Answers stream token-by-token rather than appearing all at once. This is deliberate:

• You see the answer forming as the agent reasons
• For long answers (e.g. "explain the top 5 reasons cashflow is down"), you can start reading before it finishes
• If the agent is going wrong, you can stop early by clicking the ■ Stop button

The streaming uses Server-Sent Events end-to-end. If your connection drops mid-answer, the connection indicator in the StatusBar turns red and the chat shows "[connection lost]"; reconnect and retry.

Conversations and context

Every conversation has its own memory. The agent sees:

• The last ~20 turns of the current conversation (older turns drop off)
• Anything you explicitly pinned as context
• The current workspace's settings (time zone, currency, period)

It does not see:

• Other conversations you have had (with the same agent or others)
• Other users' conversations in the same workspace
• Data from before your conversation started

To start fresh, click "New conversation" — the agent's memory resets.

Session storage

Conversations are stored in Redis under PLANA:sessions:{tenant_id}:{session_id} with a 24-hour sliding TTL. Active sessions persist across browser refreshes. After 24 hours of inactivity, a conversation is purged from Redis.

Conversations are not stored in your PostgreSQL database. If you need a permanent record of an answer (e.g. for an audit), copy the answer to a document.

When to use an agent vs the ERP

Use the agent when …	Use PLANA Business Cloud when …
You want a summary, comparison, or explanation	You want to edit / create a record
You're not sure where the data lives	You know exactly the form you need
You want to know the why	You want to know the what on a specific record
You're on mobile / away from desk	You're posting journal entries

Both are valid. The agent gives you the strategic view; the ERP gives you the operational view. People shift between them throughout the day.

Getting a better answer

A few habits that help:

• Be specific about time — "this month" is clearer than "recent"
• Be specific about subject — "products in category X" is faster than "stock"
• Ask follow-ups — the agent retains the last 20 turns; "show me the top 5" works as a follow-up to "which customers paid late?"
• Switch agents when the topic changes — pipeline questions to Sales, payment questions to Finance

What about hallucinations?

LLMs can hallucinate — make up data that looks plausible. PLANA Pulse addresses this by:

• Forcing tool use — agents are configured to call tools rather than answer from memory. If no tool returns the data, the agent says "I don't have that"
• Returning structured data — tool outputs are typed; the agent cannot invent fields the tool didn't return
• Showing tool calls in the chat — you can verify the agent's reasoning by checking which tools were called and what they returned
• The Execution log — every call is recorded with arguments, return value, and timing. Cross-check there if you suspect anything

If you spot a hallucination, please report it via the workspace's Matrix support room — PLANA tunes the agents based on real reports.

Where to read more

• Finance agent
• Warehouse agent
• Marketing agent
• Sales agent
• Conversations and history
• Safety and limits
• Execution log — the audit trail