Agents

An Agent is a configured “AI worker” that runs a task with predictable behavior: it can follow instructions, use your workspace context (RAG), and (when enabled) call tools. Agents are how you move from “single prompt” to repeatable workflows.

Mental model

Workspace: where your docs + configuration live.
Agent: a named configuration (purpose, instructions, defaults).
Run: a single execution of the agent (input → output + optional traces).

Why use Agents

Consistency: every run follows the same rules (less “it depends”).
Production control: move logic from prompts into configurations you can audit.
Scale: add RAG, routing, and tools without rewriting your app logic.
Safer integration: client calls your backend; your backend calls Brinpage with the license key.

What an Agent is made of

Publicly, you can think of an Agent as these pieces:

Name + purpose — what it does (e.g., “Support assistant”, “Doc Q&A”).
Instructions / policy — behavioral rules (tone, scope, refusal rules).
Defaults — preferred model/provider, timeouts, output style, etc.
Context strategy — how it pulls workspace knowledge (RAG tags, retrieval knobs).
Tools (optional) — controlled actions the agent may call.

How an Agent run works

Your app sends a user input (question/instructions) to your backend.
Your backend starts an Agent run in Brinpage (server-side, with the license key).
Brinpage optionally retrieves context (RAG) and applies agent policy/config.
The agent returns a result (and optionally debug/traces if enabled).

Production best practice

Always keep the license key server-side. The browser calls your endpoint, your endpoint calls Brinpage.

API usage pattern

Exact endpoints and fields depend on your workspace configuration, but the public pattern is:

bash

# 1) Your backend holds the license key
export BRINPAGE_LICENSE_KEY="bp_xxxx"

# 2) Start an agent run (server-to-server)
# (Endpoint and payload shape vary by setup; use the docs pages in /installation for your stack.)
curl -X POST https://platform.brinpage.com/api/... \
  -H "Authorization: Bearer $BRINPAGE_LICENSE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "support-assistant",
    "input": "Summarize the return policy in 3 bullets",
    "context": { "tags": ["product","policy"] },
    "debug": false
  }'

In most production apps, you wrap this inside your own backend route (e.g. /api/chat), and the browser never talks to Brinpage directly.

Common controls you should expose (carefully)

Input: the user’s message/task.
History (optional): pass conversation context for chat flows.
Tags (optional): scope RAG retrieval to a doc subset (reduces noise).
Debug (optional, server-only): return traces to help tuning (don’t show raw traces to end-users by default).

Tools and safety (if enabled)

If your agent can call tools (actions), treat it as production-critical: validate inputs, restrict permissions, and log every tool call. Tools should be allowed only when your use-case needs them — and only for the minimum scope required.

Use allow-lists (which tools can run).
Server-side authorization (never let the model decide permissions).
Rate limits and timeouts per run.
Audit logs for runs and tool calls.

Troubleshooting

401 Unauthorized: missing/invalid license key (check your server env vars).

Weak answers: review RAG tags, increase retrieval quality, or improve doc structure.

Inconsistent behavior: tighten the agent instructions/policy and reduce optional freedom.

Read: RAG Next: Config

Agents are the workflow layer. Next, we’ll document how configuration works (defaults, routing, retrieval knobs) and what you can override per request.