# AgenticOrg: complete product and evidence guide

> Generated from current repository sources for answer engines, AI assistants, evaluators, developers, and researchers.

Source version: 4.8.0. Python: >=3.12. Web application: React 19. Managed production: Google Cloud Run.

## Verified repository guide

AgenticOrg is an enterprise AI agent platform for building, running, and governing agent workflows across finance, HR, marketing, operations, back office, communications, and bounded agentic-commerce use cases. See [usage and licensing](https://github.com/mishrasanjeev/agentic-org/blob/main/LICENSING.md) for current source rights and the proposed future platform license.

> **Ownership:** AgenticOrg is owned by **Orchestrum Technologies LLP**.
>
> **Inventor / Owner:** **Sanjeev Kumar**
>
> **Contact:** [sanjeev@orchestrum.in](mailto:sanjeev@orchestrum.in) | [mishra.sanjeev@gmail.com](mailto:mishra.sanjeev@gmail.com)

Website demo and trial lead notifications default to `sanjeev@orchestrum.in`.
Self-hosted operators can select their own single marketing inbox with
`AGENTICORG_DEMO_NOTIFY_TO`. This does not redirect requester confirmations,
workspace notifications, or account-recovery email, and does not replace SMTP setup.
>
> See the canonical [ownership and contact statement](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/OWNERSHIP.md) and [NOTICE](https://github.com/mishrasanjeev/agentic-org/blob/main/NOTICE).

[Website](https://agenticorg.ai) | [Application](https://app.agenticorg.ai) | [Playground](https://agenticorg.ai/playground) | [User manual](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/user-guide/README.md) | [Technical documentation](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/README.md) | [Current product status](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/PRODUCT_STATUS.md) | [Security policy](https://github.com/mishrasanjeev/agentic-org/blob/main/SECURITY.md)

![Python 3.12+](https://img.shields.io/badge/Python-3.12%2B-3776AB)
![React 19](https://img.shields.io/badge/React-19-149ECA)
![License: Apache 2.0](https://img.shields.io/badge/License-Apache--2.0-blue)

## Source of truth

Live product totals and the deployed product version are published by the public [product facts endpoint](https://app.agenticorg.ai/api/v1/product-facts):

    GET https://app.agenticorg.ai/api/v1/product-facts

The response contains version, agent_count, connector_count, and tool_count. Do not copy those values into documentation, page copy, or tests: they are computed from runtime registries and can change independently of a documentation release. The version declared for source builds is in [pyproject.toml](https://github.com/mishrasanjeev/agentic-org/blob/main/pyproject.toml).

Billing limits and list prices come from [core/billing/catalog.py](https://github.com/mishrasanjeev/agentic-org/blob/main/core/billing/catalog.py). Production deployment behavior comes from [scripts/deploy_cloud_run.sh](https://github.com/mishrasanjeev/agentic-org/blob/main/scripts/deploy_cloud_run.sh).

## Current release at a glance

### Bring your own channels and AI credentials

New agents default to `gemini-3.5-flash-lite`; explicitly selected models remain
unchanged. Save your Google or other provider key in the protected AI credential
settings. Model selection, fallback and company scope remain configurable.

The **Channels** dashboard connects your own WhatsApp Cloud API, Meta Messenger,
Telegram, Viber, inbound Mailgun email or signed gateway to an agent or workflow.
Credentials are encrypted, callbacks are authenticated, unlinked messages require
review, and private sender links delegate only your current permissions. Existing
Twilio voice/call setup and remote MCP tool discovery remain separate integrations.
Native channel replies are optional status notices, not private result exports.

Follow the [channel account and workflow guide](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/user-guide/channel-workflows.md)
for account creation, callback registration, sender linking and verification.
Local wire-contract tests are not proof of real provider-account delivery.

The production platform currently includes governed agent/workflow execution,
document ingestion with scanned-document OCR, signed Twilio voice with
provider-managed STT/TTS, tenant-scoped browser RPA, Python and TypeScript SDKs,
MCP/A2A surfaces, and the bounded Shopify-to-OACP commerce runtime. See the
[current product status](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/PRODUCT_STATUS.md) for the exact shipped,
configuration-dependent, and not-shipped boundaries.

External actions remain explicit. A voice provider, connector, browser script,
buyer channel, payment rail, merchant system, or POS path is usable only when
the target tenant has the required credentials, scopes, configuration, and
provider approval.

### Governed business cases

The repository includes a tenant-gated business onboarding case workflow with
read-only provider investigation, a cited memo, deterministic policy scoring,
screening dispositions, human review, and an auditable hand-off. Provider calls
are refused unless the active role agent, registered tools, exact local case
purpose, and delegated grant all authorize the call. This case-specific check
is strict even if general tool enforcement is in `off` or `warn` mode.

AgenticOrg pins `grantex==0.7.1` and calls its enforcement check with the
grant token, connector, tool and any numeric amount. It does not pass a case id or case
purpose, so a token's case purpose and per-case caps are **not** checked on
this path. The role's `case_purposes` list is a local AgenticOrg control, and
pooled grants are not bound to one case. Decision and
analyst actions still require a signed-in human; API keys, agent tokens, and
MCP tools cannot act as that human. The case runtime is off for a tenant until
enabled and configured. This source description is not a claim that a particular
hosted deployment has enabled the workflow. See the [case lifecycle and setup](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/governance/case-lifecycle.md),
[grant-enforcement runbook](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/operations/grant-enforcement.md), and
[decision requests](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/governance/decision-requests.md).

Voice, email, OCR, and browser RPA can be exercised together before release
with the Docker-backed [local multichannel simulation](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/local-multichannel-simulation.md).
It uses fresh PostgreSQL, local Mailpit delivery, real Tesseract, and optional
real Playwright Chromium while keeping paid calls and production mutations off.

The dashboard's Recent Activity queries audit records. The separate internal
live-feed pipeline persists events per tenant *when published* and can replay
them by sequence after a WebSocket interruption. Its only writer is the
conversation supervisor console (off by default behind
`AGENTICORG_CONVERSATION_V2_ENABLED`), which announces conversation changes
without message text for the Conversations screen; other operational event
writers are not wired to that pipeline. Its browser component exposes
connection/catch-up status without raw payload display; it is not mounted as
the dashboard's live stream. Broker reconnection, bounded socket fanout, and
periodic credential revalidation are covered by local tests. Production
latency, throughput, and availability remain unmeasured. The
[activity delivery guide](https://agenticorg.ai/resources/agent-activity-audit-and-live-feed)
explains the boundary. The [scale and resilience assessment](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/reports/ema-agenticorg-gap-and-resilience-2026-09-24.md)
tracks remaining connection-scale, load, and restore work; the
[recovery guide](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/BACKUP_AND_DR.md) separates planned targets from proven
production controls.

### AI spend intelligence

AI spend intelligence measures AI spend in rupees against the organisation's
own structure. It is off by default behind
`AGENTICORG_SPEND_INTELLIGENCE_ENABLED`: while it is off,
`GET /api/v1/spend/status` answers `enabled: false`, every other spend route
returns 404 and nothing is metered. Phase 1 is API-only; the application has
no spend screen yet.

When a deployment turns it on, administrators keep the reference data spend is
measured against: an organisation tree, source mappings, model aliases,
effective-dated rate cards (a contract card ranks above a list card, with
cached-input prices, volume tiers and a stored batch discount that phase 1 does
not yet apply), FX rates that convert every price
to INR, and commitments. Every metered model call is written as usage records
with server-side attribution, priced at the rate card in force on its billing
date (or the deployment's list price for model tokens), and so are embeddings,
OCR pages, speech minutes, priced tool calls, storage GB-days and in-house GPU
node hours. Daily rollups, coverage
with the unattributed share, meter gaps and audited maintenance jobs sit on
these records. Provider invoices are imported and reconciled per billing month
within a 1% match tolerance; a difference is accepted with a reason by an
administrator other than the invoice importer. `GET /api/v1/spend/gate`
reports the Gate 1 status of a month: at least 98% of INR spend attributed to
a business unit, department, team or cost centre, with no unpriced,
unconverted or FX-pending record, and every provider reconciled within 1%.

```mermaid
flowchart TD
  flag{"AGENTICORG_SPEND_INTELLIGENCE_ENABLED"}
  flag -->|"off, the default"| off["Only GET /api/v1/spend/status answers, other spend routes are 404"]
  flag -->|"on"| ref["Reference data: organisation tree, source mappings, model aliases, rate cards, FX to INR, commitments"]
  usage["Model calls, embeddings, OCR pages, speech minutes, priced tool calls, storage GB-days, GPU node hours"] --> meter["Meter and writer: server-side attribution and pricing"]
  ref --> meter
  meter --> records["Usage records"]
  records --> rollups["Daily rollups, coverage and the unattributed share"]
  invoices["Imported provider invoices"] --> recon["Reconciliation per provider and billing month"]
  records --> recon
  recon -->|"outside the 1% match tolerance"| accept["Acceptance with a reason by a second administrator"]
  rollups --> gate(["Gate 1 status: at least 98% attributed and every provider within 1%"])
  recon --> gate
```

Rate cards, commitments, prices, invoices, reconciliations and the gate are
answered only to a human administrator or auditor. Other readers see usage
filtered by agent visibility and are refused tenant-wide figures. Spend
dashboards, budgets, spend alerts, forecasting, statements and month close
are later phases. See the [user guide](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/user-guide/ai-spend-intelligence.md),
the [feature reference](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/finops/spend-intelligence.md) and the
[rollout runbook](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/runbooks/spend-intelligence.md).

## What is in this repository

| Area | Current implementation |
| --- | --- |
| Agent runtime | FastAPI and LangGraph runtime with model routing, tool invocation, confidence handling, retry policy, and persisted execution state |
| Agent authoring | Built-in agent definitions, custom agents, prompt templates, organization hierarchy, and a no-code UI |
| Workflows | Workflow definitions, runs, schedules, conditions, approvals, and audit events |
| Governance | Tenant and role boundaries, scoped tools, human-in-the-loop queues, shadow evaluation, policy checks, and kill-switch patterns |
| Integrations | Native connector registry plus optional integration gateways; actual availability depends on credentials, scopes, provider access, and tenant configuration |
| Knowledge and channels | Native and OCR document ingestion/search, reports, notifications, signed Twilio voice calls, RPA, and other configured channels |
| Developer access | REST API, Python SDK and CLI, TypeScript SDK, MCP server, legacy A2A-shaped task APIs, and source-implemented A2A v1 HTTP+JSON synchronous text |
| Commerce | Merchant-scoped Shopify read-only sync, OACP artifact intake/cache, buyer-safe answers, public catalog surfaces, and prepared provider or POS handoffs |
| Operations | PostgreSQL, Redis, object storage, observability hooks, migrations, security checks, and Cloud Run deployment tooling |
| AI spend intelligence | Off by default; API-only organisation tree, source mappings, rate cards, FX to INR, commitments, attributed usage records for model calls and non-token usage, daily rollups, coverage, invoice reconciliation, maker-checker acceptance, and the Gate 1 status |

A source definition is not evidence that a specific tenant has connected the provider or enabled write access. The Connectors page now separates registration from configured credentials and a recent, stale, failed, or missing health check. That evidence does not verify provider scopes, API contract coverage, sustained sync, or an error budget. Connector actions still require approved credentials, scopes, policies, and provider availability.

## Capability status

### Implemented in the platform

- Agent definitions and tenant-created agents
- Agent and workflow execution through authenticated APIs
- Human approval queues and configurable escalation conditions
- Audit records for governed runtime activity
- Prompt templates, organization structure, and role-aware application views
- Native connector definitions and a scoped tool gateway
- Public A2A and MCP discovery with authenticated execution paths
- Python and TypeScript client packages plus an MCP server package
- Hosted billing limits and checkout integration
- OACP commerce configuration, Shopify read-only sync, artifact caching, buyer channels, and safe handoff preparation

### Configuration-dependent or provider-gated

- LLM calls require a configured supported model provider or a local model runtime.
- Each connector requires provider credentials, tenant authorization, and the relevant scopes. Follow the [connector setup guide](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/user-guide/connectors.md) for native registry names, credential fields, health checks, and the rollout-gated catalog prefill. A registered row is not proof of a live provider connection.
- Composio is an optional integration gateway; its catalog is not the same as the native connector registry.
- Document OCR ships with Tesseract, Poppler, and LibreOffice in the production image. See [Knowledge ingestion](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/knowledge-ingestion.md).
- The production voice path uses signed Twilio webhooks with provider-managed STT/TTS and encrypted transcript storage. See [Voice runtime](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/voice-runtime.md).
- Jev/System One support is implemented as an advisory, shadow-ready integration, but TypeSafe enrollment is currently closed to new users. Production remains `off` until TypeSafe access is granted and a measured evaluation is approved. See [Jev integration](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/jev-agenticorg-integration.md).
- The public [evaluation page](https://agenticorg.ai/evals) exposes a read-only Jev shadow plan: synthetic corpus coverage, bounded sampling and budget controls, and explicit review gates. It does not call Jev or enable active routing.
- The measured Jev shadow runner is explicit and local: `python scripts/run_jev_shadow_evaluation.py --dry-run`; `--live` requires a TypeSafe-issued `TYPESAFE_API_KEY`, bounded gates, and an operator-approved output path. Do not invent, commit, or paste a key into the repository.
- Browser automation includes tenant-scoped scripts, schedules, durable history,
  and approved-domain egress controls. A run remains an explicit external
  action. See [RPA runtime](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/rpa-runtime.md).
- Outbound notifications and local-model profiles require their supporting services.
- AI spend intelligence is off by default. Nothing is metered until `AGENTICORG_SPEND_INTELLIGENCE_ENABLED`
  is set on the API, worker, and beat services. Attribution follows the organisation tree and mappings a
  tenant administrator enters; prices come from the tenant's rate cards, else the deployment's list prices
  for model tokens, converted to INR with the tenant's FX rates. Follow the
  [rollout and enablement runbook](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/runbooks/spend-intelligence.md).
- Many governance and BFSI services ship in source but are off by default, each behind its own
  `AGENTICORG_*` setting: the model gateway, guardrail hooks and enforcement, operator override,
  residency enforcement, the audit chain, tracing and synthetic checks, runtime limits and memory, the
  visual workflow builder, prompt maker-checker and comparison, evaluation datasets and the promotion
  gate, the agent registry, governance inventory and model cards, FinOps attribution, thresholds and
  forecast, conversational services, content services, document processing, workbenches, speech and
  transaction intelligence, lineage and personalisation. A default installation has none of them on.
  See the [feature switches](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/user-guide/self-hosting.md#feature-switches-that-ship-off) table and
  the [guide to the default-off screens](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/user-guide/review-and-operations-screens.md).
- SSO, SCIM, enterprise support, and custom SLAs depend on plan and deployment configuration.
- WhatsApp, Telegram, payment-provider, bank, POS, and merchant-system flows require provider setup and verified callbacks or adapters.
- WooCommerce, ERP, PIM, OMS, WMS, custom commerce APIs, and additional payment rails can be recorded as adapter-ready configuration but are not represented as active execution paths until an approved adapter exists.

### Explicit non-goals and boundaries

- OACP artifacts do not create orders, reserve inventory, create mandates, capture payments, issue refunds, or prove a paid state.
- AgenticOrg does not replace the merchant, bank, payment provider, POS, or SaaS system as its source of record.
- Cached commerce evidence can support an answer or a prepared handoff; provider-owned execution must be confirmed by the provider.
- A connector listed in source is not proof of a live customer integration.
- Example workflows and editorial content are not performance guarantees.
- Security controls in the repository are not a claim of third-party certification.

## How the runtime fits together

    Browser or SDK
        |
        v
    React 19 application / FastAPI API
        |
        +-- Authentication, tenant context, roles, and scopes
        +-- Agent registry and LangGraph execution
        +-- Workflow engine, schedules, and approval queues
        +-- Tool gateway and connector adapters
        +-- Audit, evaluation, observability, and cost records
        |
        +-- PostgreSQL / Cloud SQL
        +-- Redis
        +-- GCS or compatible object storage
        +-- Configured LLM and external service providers

The managed production path runs separate API and UI services on Google Cloud Run. Artifact Registry images are commit-pinned, migrations can run before rollout, and traffic movement is explicit. Legacy Kubernetes material is not the current production path.

## OACP commerce boundary

AgenticOrg owns the buyer and seller agent runtime around OACP-backed commerce. [Grantex](https://grantex.dev) owns trust authority, protocol and policy governance, canonical artifacts, artifact verification, and adapter authority. Shopify and merchant systems remain operational sources of record. Pine Labs Plural/P3P, banks, POS systems, and payment providers own their execution rails.

The current supported source path is:

1. A merchant saves tenant-, merchant-, store-, and seller-agent-scoped configuration.
2. AgenticOrg stores Shopify credentials through the approved custody path.
3. AgenticOrg performs read-only Shopify Admin GraphQL sync.
4. Public-safe evidence is submitted to the configured Grantex authority path.
5. Issued OACP artifacts are cached with freshness, scope, risk, and revocation posture.
6. Buyer surfaces answer from valid artifacts and disclose source and freshness.
7. Purchase intent becomes a non-executing provider, merchant, or POS handoff, or a fail-closed blocker.
8. Only a verified provider or merchant callback can confirm the external outcome.

Start with [docs/oacp/README.md](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/oacp/README.md) and the [runtime launch closure PRD](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/oacp/runtime-launch-closure-prd.md).

## Requirements

- Python 3.12 or newer
- Node.js 22.22 or newer (the UI's router requires it; CI uses 22.22.0)
- Docker with Docker Compose for local PostgreSQL and Redis
- At least one supported LLM provider key, or a configured local model runtime, for model-backed execution

The UI currently uses React 19. Dependency versions are declared in [pyproject.toml](https://github.com/mishrasanjeev/agentic-org/blob/main/pyproject.toml) and [ui/package.json](https://github.com/mishrasanjeev/agentic-org/blob/main/ui/package.json).

## Local development

Clone and configure the repository:

    git clone https://github.com/mishrasanjeev/agentic-org.git
    cd agentic-org
    cp .env.example .env

Install the platform and development extras:

    python -m venv .venv
    python -m pip install -e ".[v4,dev]"

Start local dependencies:

    docker compose up -d postgres redis minio

Run migrations and the API. `AGENTICORG_ENV` must be in the shell environment,
not only in `.env`: the credential vault reads the process environment, and
outside a local, dev, development, test or CI runtime it refuses to start
without a real vault key.

    export AGENTICORG_ENV=development
    python scripts/alembic_migrate.py
    uvicorn api.main:app --host 0.0.0.0 --port 8000 --reload

In another terminal, install and run the UI:

    cd ui
    npm ci
    npm run dev

Do not use example secrets in staging or production. Configure real secrets through the approved secret-management path.

Optional Compose profiles include local CPU/GPU model runtimes and supporting RAG or voice services. Review [docker-compose.yml](https://github.com/mishrasanjeev/agentic-org/blob/main/docker-compose.yml) before enabling a profile because hardware, images, and credentials vary by feature.

## Public API and protocols

Application API routes are mounted below /api/v1, except the standard root
A2A Agent Card discovery path.

| Surface | Purpose | Authentication posture |
| --- | --- | --- |
| GET /api/v1/health | Service health | Public |
| GET /api/v1/product-facts | Live version and registry totals | Public |
| GET /.well-known/agent-card.json | A2A v1 generic Agent Card (after release and ingress configuration) | Public |
| GET /api/v1/a2a/extendedAgentCard | Merchant-specific seller card | Merchant-issued buyer credential |
| POST /api/v1/a2a/message:send | A2A v1 synchronous text request | Buyer credential for seller Q&A, or scoped tenant credential for non-commerce agents |
| GET /api/v1/a2a/agent-card | Legacy AgenticOrg discovery card; not A2A v1 | Public |
| GET /api/v1/a2a/.well-known/agent.json | Legacy discovery alias; not A2A v1 | Public |
| GET /api/v1/mcp/tools | MCP-compatible agent discovery | Public |
| Agent, workflow, tool, billing, and commerce mutations | Tenant operations | Authenticated and scoped |

Interactive OpenAPI documentation is available from the API service when enabled by the deployment. The detailed route inventory is maintained in [docs/route_inventory.json](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/route_inventory.json), and narrative API documentation is in [docs/api-reference.md](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/api-reference.md).

An external buyer agent need not run on AgenticOrg. The merchant can issue a
revocable, scope-bound buyer credential for any A2A v1 HTTP+JSON client, while
seller answers remain non-binding and sourced from the OACP cache. See the
[A2A interoperability guide](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/a2a-interoperability.md) for the exact
identity limits, SDK calls, migration/ingress requirements, and unsupported
transports. This repository implementation does not imply that a named buyer
platform has installed or endorsed AgenticOrg.

### Python SDK and CLI

See [sdk/README.md](https://github.com/mishrasanjeev/agentic-org/blob/main/sdk/README.md).

    pip install agenticorg
    agenticorg agents list
    agenticorg a2a card

SDK `0.4.0` covers agents, workflows, connector diagnostics, knowledge/OCR,
voice, RPA, local bridges, and the seller-commerce runtime. External-action
methods such as outbound calls, RPA runs, connector sync, and bridge routing
remain explicit calls and still require tenant authorization. Server features
may require a newer deployment than the installed client, so consumers should
check package and server release notes.

### TypeScript SDK

See [sdk-ts/README.md](https://github.com/mishrasanjeev/agentic-org/blob/main/sdk-ts/README.md).

    npm install agenticorg-sdk

The TypeScript `0.4.0` resource surface mirrors the Python runtime coverage,
including knowledge/OCR, voice, RPA, bridges, and commerce preparation APIs.

### MCP server

See [mcp-server/README.md](https://github.com/mishrasanjeev/agentic-org/blob/main/mcp-server/README.md).

    npx agenticorg-mcp-server

The MCP package exposes governed AgenticOrg agent and commerce discovery surfaces. It does not grant an MCP client unrestricted access to every connector action.

For the reverse direction, **Connectors > Remote MCP** registers a tenant-owned
HTTPS Streamable HTTP server with encrypted bearer credentials, discovers its
tools, and shares the persisted catalog with agent selection and runtime dispatch.
Reviewed read tools can execute subject to grants and action policy; write tools
remain contained. Discovery is not proof of every upstream provider capability.
See the [connection, review, probe and agent-run workflow](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/user-guide/connectors.md).

## Pricing and limits

The hosted plan source of truth is the typed `PUBLIC_PLAN_CATALOG` in [core/billing/catalog.py](https://github.com/mishrasanjeev/agentic-org/blob/main/core/billing/catalog.py). A compatibility view in `core/billing/limits.py` is derived from that catalog.

| Plan | USD list price | INR list price | Agents | Runs | Storage |
| --- | ---: | ---: | ---: | ---: | ---: |
| <!-- claim-id: BILLING-CATALOG-PUBLIC-PLANS --> Free | $0/month | INR 0/month | 3 | 1,000/month | 1 GB |
| <!-- claim-id: BILLING-CATALOG-PUBLIC-PLANS --> Pro | $99/month | INR 9,999/month | 15 | 10,000/month | 50 GB |
| <!-- claim-id: BILLING-CATALOG-PUBLIC-PLANS --> Enterprise | $499/month | INR 49,999/month | Unlimited | Unlimited | Unlimited |

The repository is Apache-2.0 licensed. Infrastructure, model-provider, external API, payment-provider, and support costs are separate from the software license.

## Security and governance

The codebase includes:

- Tenant, role, and scope checks around protected API operations
- Configurable human approvals and confidence or policy gates
- Scoped connector tools and a centralized tool gateway
- Secret-reference patterns for connector and cloud credentials
- Configurable PII redaction before model calls and in logs
- JWT verification through PyJWT with cryptographic support
- Rate limiting, security headers, and authentication-state controls
- Dependency, static-analysis, container, and regression security checks
- Audit and observability records for governed operations
- Fail-closed OACP freshness, revocation, and provider-boundary checks

Production security depends on correct deployment configuration, key custody, provider settings, tenant policies, and operational monitoring. Report vulnerabilities through [SECURITY.md](https://github.com/mishrasanjeev/agentic-org/blob/main/SECURITY.md); do not open a public issue for a suspected vulnerability.

## Testing

Backend:

    pytest

Focused backend checks can be run by directory or file:

    pytest tests/unit
    pytest tests/regression
    pytest tests/connector_harness

Frontend:

    cd ui
    npm ci
    npm run lint
    npm run typecheck
    npm test
    npm run build

Browser tests:

    cd ui
    npx playwright test

Playwright suites require the target application and any documented test credentials or fixtures. CI workflow files under [.github/workflows](https://github.com/mishrasanjeev/agentic-org/blob/main/.github/workflows) are the source of truth for which suites run on each event; the README does not claim that every E2E suite runs on every push.

## Production deployment

The current managed rollout helper targets Google Cloud Run:

    bash scripts/deploy_cloud_run.sh --sha <commit-sha> --yes

Useful modes include:

    bash scripts/deploy_cloud_run.sh --sha <commit-sha> --skip-build --with-migrations --yes
    bash scripts/deploy_cloud_run.sh --sha <commit-sha> --skip-build --traffic preserve --yes
    bash scripts/deploy_cloud_run.sh --sha <commit-sha> --dry-run

The helper requires a clean checkout at the exact deploy SHA, stages revision-specific images, verifies image and commit metadata, supports migration-first deployment, probes health, and moves traffic according to the selected mode. Read the script help and [docs/deployment.md](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/deployment.md) before using production credentials.

Default script configuration places Cloud Run services in asia-southeast1 and Artifact Registry in asia-south1. Both are configurable. Older Kubernetes material is retained only for historical or alternative deployment context.

## Repository map

    api/                 FastAPI application and versioned routes
    auth/                Authentication and authorization middleware
    core/                Agent runtime, models, billing, commerce, and orchestration
    connectors/          Native connector implementations and framework
    workflows/           Workflow definitions and runtime helpers
    sdk/                 Python SDK and CLI
    sdk-ts/              TypeScript SDK
    mcp-server/          MCP server package
    ui/                  React 19 application and public web assets
    migrations/          Database migrations
    observability/       Metrics, tracing, and logging helpers
    tests/               Backend unit, regression, security, and integration tests
    ui/e2e/              Playwright browser tests
    docs/                Product, architecture, operations, and protocol documentation
    scripts/             Validation, migration, release, and deployment helpers

## Search and answer-engine assets

The public site includes conventional search and answer-engine discovery assets:

- [robots.txt](https://agenticorg.ai/robots.txt)
- [sitemap.xml](https://agenticorg.ai/sitemap.xml)
- [llms.txt](https://agenticorg.ai/llms.txt)
- [llms-full.txt](https://agenticorg.ai/llms-full.txt)
- Per-route titles, descriptions, canonicals, social metadata, and structured data
- Crawlable blog, resource, product, protocol, solution, trust, and legal pages

The two llms files are generated by [ui/scripts/generate-llms.mjs](https://github.com/mishrasanjeev/agentic-org/blob/main/ui/scripts/generate-llms.mjs). They are supplemental machine-readable navigation documents, not replacements for crawlable HTML, accurate structured data, robots controls, or the sitemap.

To refresh the tracked sitemap and llms copies plus route JSON-LD CSP hashes:

    cd ui
    npm run seo:sync
    npm run seo:verify

## Documentation

- [End-user manual: first agent, everyday operations and BFSI playbooks](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/user-guide/README.md). The UI serves this same Markdown content at [agenticorg.ai/docs](https://agenticorg.ai/docs), with full-text search, visual process flows, print-friendly guides and mobile navigation. The [docs.agenticorg.ai](https://docs.agenticorg.ai) alias has configured Cloud DNS and managed HTTPS; its hosting and verification instructions live in the [documentation runbook](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/runbooks/documentation-site.md).
- [Functional BFSI coverage and open gaps](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/bfsi/functional-coverage.md) shows what is implemented, partial or unavailable, with verification scenarios and product boundaries.
- [Public BFSI capability status](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/user-guide/bfsi-capability-status.md) gives readers a plain-language summary of the same assessment, including unfinished work.
- [Documents, conversations, calls and workbenches](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/user-guide/review-and-operations-screens.md) covers the console screens of services that ship off by default and the setting each needs.
- [Documentation site publishing and subdomain runbook](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/runbooks/documentation-site.md)
- [Documentation home](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/README.md)
- [Current product status](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/PRODUCT_STATUS.md)
- [Architecture](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/architecture.md)
- [API reference](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/api-reference.md)
- [Deployment](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/deployment.md)
- [AI spend intelligence user guide](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/user-guide/ai-spend-intelligence.md), [feature reference](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/finops/spend-intelligence.md) and [rollout and enablement runbook](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/runbooks/spend-intelligence.md)
- [Knowledge ingestion and OCR](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/knowledge-ingestion.md)
- [Local voice, email, RPA, and OCR simulation](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/local-multichannel-simulation.md)
- [Voice runtime](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/voice-runtime.md)
- [RPA runtime](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/rpa-runtime.md)
- [OACP runtime documentation](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/oacp/README.md)
- [External A2A buyer and seller access](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/a2a-interoperability.md)
- [Local synthetic seller and independent A2A buyer demo](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/a2a-commerce-demo.md)
- [Guided merchant-to-external-buyer A2A commerce journey](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/user-guide/seller-a2a-commerce-journey.md)
- [Production smoke runbook](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/runbooks/production_smoke.md)
- [Testing guide](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/TEST_PLAN.md)
- [Python SDK](https://github.com/mishrasanjeev/agentic-org/blob/main/sdk/README.md)
- [TypeScript SDK](https://github.com/mishrasanjeev/agentic-org/blob/main/sdk-ts/README.md)
- [MCP server](https://github.com/mishrasanjeev/agentic-org/blob/main/mcp-server/README.md)
- [Changelog](https://github.com/mishrasanjeev/agentic-org/blob/main/CHANGELOG.md)
- [Roadmap](https://github.com/mishrasanjeev/agentic-org/blob/main/ROADMAP.md)

The [documentation home](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/README.md) labels current, configuration-dependent,
historical, and target-design material. Dated audits, old PRDs, and incremental
implementation reports remain useful history, but they do not override current
code, OpenAPI, runbooks, retained release evidence, or live product facts.

## Contributing

Read [CONTRIBUTING.md](https://github.com/mishrasanjeev/agentic-org/blob/main/CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](https://github.com/mishrasanjeev/agentic-org/blob/main/CODE_OF_CONDUCT.md). Keep pull requests focused, add tests for behavior changes, and update generated public documentation when a source-of-truth field changes.

## License

AgenticOrg is licensed under the [Apache License 2.0](https://github.com/mishrasanjeev/agentic-org/blob/main/LICENSE).

Approved prospective policy (software adoption pending): personal/internal use is free;
commercializing the platform requires an agreement with Orchestrum Technologies
LLP. Write to [sanjeev@orchestrum.in](mailto:sanjeev@orchestrum.in).
The policy covers existing and new covered users, not just new accounts;
existing hosted customers transition through applicable notice and agreement terms.
See [usage and licensing](https://github.com/mishrasanjeev/agentic-org/blob/main/LICENSING.md); current Apache-2.0 rights remain unchanged.
The concrete transition uses a separate self-use/commercial-agreement license
for eligible future platform material, not an added condition on legacy code.


## Machine-readable authority notes

- Live deployed totals and version: https://app.agenticorg.ai/api/v1/product-facts
- Hosted prices and limits: core/billing/catalog.py
- Production rollout: scripts/deploy_cloud_run.sh
- Current commerce contract: docs/oacp/README.md
- A source definition means implementation code exists; it does not mean a tenant enabled it.
- A public article title is a topic, not independent proof of an outcome.

## Built-in agent source index

These names are parsed from core/agents. The product facts endpoint is authoritative for totals, and tenant-created agents are not included in this source index.

### Marketing

- Abm (abm)
- Brand Monitor (brand_monitor)
- Campaign Pilot (campaign_pilot)
- Competitive Intel (competitive_intel)
- Content Factory (content_factory)
- Crm Intelligence (crm_intelligence)
- Seo Strategist (seo_strategist)
- Social Media (social_media)

### Finance

- Ap Processor (ap_processor)
- Ar Collections (ar_collections)
- Close Agent (close_agent)
- Fpa Agent (fpa_agent)
- Recon Agent (recon_agent)
- Tax Compliance (tax_compliance)

### Operations

- Compliance Guard (compliance_guard)
- Contract Intelligence (contract_intelligence)
- It Operations (it_operations)
- Support Deflector (support_deflector)
- Support Triage (support_triage)
- Vendor Manager (vendor_manager)

### Back Office

- Facilities Agent (facilities_agent)
- Legal Ops (legal_ops)
- Risk Sentinel (risk_sentinel)

### HR

- Ld Coordinator (ld_coordinator)
- Offboarding Agent (offboarding_agent)
- Onboarding Agent (onboarding_agent)
- Payroll Engine (payroll_engine)
- Performance Coach (performance_coach)
- Talent Acquisition (talent_acquisition)

## Native connector source index

These names are parsed from connectors. A listing does not prove credentials, subscriptions, scopes, or provider access. Optional marketplace catalogs are separate. Use the product facts endpoint for current native connector and tool totals; do not sum files or tool bindings.

### Marketing

- Ahrefs - authentication type: api_token
- Bombora - authentication type: api_key
- Brandwatch - authentication type: oauth2
- Buffer - authentication type: oauth2
- G2 - authentication type: api_key
- Ga4 - authentication type: oauth2
- Google Ads - authentication type: oauth2
- Hubspot - authentication type: oauth2
- Linkedin Ads - authentication type: oauth2
- Mailchimp - authentication type: basic
- Meta Ads - authentication type: oauth2
- Mixpanel - authentication type: basic
- Moengage - authentication type: basic
- Salesforce - authentication type: oauth2
- Trustradius - authentication type: api_key
- Wordpress - authentication type: basic

### Finance

- Banking Aa - authentication type: aa_oauth2
- Gstn - authentication type: gsp_dsc
- Gstn Sandbox
- Income Tax India - authentication type: dsc
- Netsuite - authentication type: token
- Oracle Fusion - authentication type: basic
- Pinelabs Plural - authentication type: oauth2
- Professional Tax - authentication type: state_portal
- Quickbooks - authentication type: oauth2
- Sap - authentication type: odata_oauth2
- Stripe - authentication type: api_key
- Tally - authentication type: tdl_xml
- Traces - authentication type: deductor_portal
- Zoho Books - authentication type: oauth2

### Operations

- Confluence - authentication type: oauth2
- Jira - authentication type: oauth2
- Mca Portal - authentication type: dsc
- Pagerduty - authentication type: api_key
- Sanctions Screening - authentication type: none
- Servicenow - authentication type: rest_oauth2
- Zendesk - authentication type: api_token

### HR

- Darwinbox - authentication type: api_key_oauth2
- Docusign - authentication type: jwt
- Epfo - authentication type: dsc
- Greenhouse - authentication type: api_key
- Keka - authentication type: api_key
- Linkedin Talent - authentication type: oauth2
- Okta - authentication type: scim_oauth2
- Zoom - authentication type: oauth2

### Communications and Cloud

- Github - authentication type: pat_oauth2
- Gmail - authentication type: oauth2
- Google Calendar - authentication type: oauth2
- Langsmith - authentication type: api_key
- S3 - authentication type: service_account
- Sendgrid - authentication type: api_key
- Slack - authentication type: bolt_bot_token
- Twilio - authentication type: api_key_secret
- Twitter - authentication type: oauth2
- Whatsapp - authentication type: meta_business
- Youtube - authentication type: oauth2

## Complete canonical public-page index

- [AgenticOrg](https://agenticorg.ai): AgenticOrg is an open-source enterprise agent runtime for workflows, knowledge and OCR, signed voice, browser RPA, business-system integration, governed actions, and buyer/seller commerce agents.
- [Pricing](https://agenticorg.ai/pricing): AgenticOrg offers Free, Pro, and Enterprise tiers. Published limits and prices are generated from the same plan definitions used by the billing service.
- [Agent Playground](https://agenticorg.ai/playground): The public playground demonstrates representative agent interactions with sample data. Its outputs are examples, not production decisions or performance guarantees.
- [Agent Evaluations](https://agenticorg.ai/evals): AgenticOrg evaluations help teams assess quality, safety, reliability, security, latency, and cost before promoting an agent from testing into governed use.
- [Integration Workflow](https://agenticorg.ai/integration-workflow): The integration workflow takes a connection from discovery through scoped configuration, validation, shadow testing, approval, activation, and ongoing audit.
- [Open Agentic Commerce Protocol](https://agenticorg.ai/open-agentic-commerce-protocol): AgenticOrg ships the bounded Shopify-to-OACP runtime while separating merchant facts, Grantex artifact authority, buyer-agent behavior, and provider/POS execution authority.
- [How Grantex Works](https://agenticorg.ai/how-grantex-works): Governed cases check registered role tools, an exact local purpose allowlist, and a delegated grant before provider calls; case decisions still require a signed-in human.
- [AI Agents for CA Firms](https://agenticorg.ai/solutions/ca-firms): AgenticOrg can help CA firms coordinate repeatable client-service workflows while keeping filings, payments, and other consequential actions within configured approval and provider boundaries.
- [AI Agents for Finance](https://agenticorg.ai/solutions/cfo): Finance teams can compose agents around defined tasks and data sources while retaining human approval for high-impact actions and evidence for review.
- [AI Agents for HR](https://agenticorg.ai/solutions/chro): HR teams can use agents for repeatable coordination and information tasks while keeping sensitive data scoped and employment decisions under human authority.
- [AI Agents for Marketing](https://agenticorg.ai/solutions/cmo): Marketing teams can coordinate research and campaign workflows using scoped tools, review gates, versioned prompts, and owner-defined evaluation measures.
- [AI Agents for Operations](https://agenticorg.ai/solutions/coo): Operations teams can route and coordinate repetitive workflows using agents subject to escalation rules, action scopes, approval requirements, and audit evidence.
- [AI Agents for Back Office](https://agenticorg.ai/solutions/cbo): Back-office teams can assemble traceable workflows around documents, cases, and internal systems while preserving review and authorization boundaries.
- [Blog](https://agenticorg.ai/blog): The AgenticOrg blog covers implementation patterns, operating practices, governance decisions, and protocol boundaries for enterprise AI agents.
- [Resource Library](https://agenticorg.ai/resources): The resource library provides educational guides for teams assessing, designing, integrating, governing, and operating enterprise AI agents.
- [Support](https://agenticorg.ai/support): Use the AgenticOrg support page to reach the team about product evaluation, deployment, account and billing questions, or responsible security disclosure.
- [Service Status](https://agenticorg.ai/status): The status page reports the current availability information exposed by AgenticOrg and provides a support path when an organization needs incident-specific help.
- [Privacy Policy](https://agenticorg.ai/privacy): The privacy policy explains how AgenticOrg handles personal information and how people can submit questions or requests about that handling.
- [Terms of Service](https://agenticorg.ai/terms): The terms of service describe the rules and responsibilities that apply when a customer or user accesses AgenticOrg services.
- [Refund and Cancellation Policy](https://agenticorg.ai/refund): The refund and cancellation policy describes how subscription cancellation and eligible billing requests are handled.
- [AgenticOrg Documentation](https://agenticorg.ai/docs): The public user manual includes task-based setup and operating guides, source-verified product boundaries, troubleshooting and five end-to-end BFSI reference workflows.
- [Start here](https://agenticorg.ai/docs/start-here): Choose a practical learning path for your role and understand what AgenticOrg does, what it needs, and who stays in control.
- [Your first useful agent](https://agenticorg.ai/docs/first-agent): Create a document-review agent, upload a sample procedure, run a bounded task, inspect evidence, and prepare a pilot.
- [Workspace, companies and roles](https://agenticorg.ai/docs/workspace-and-roles): Set up your organization, invite colleagues, choose the right company, and understand why different users see different controls.
- [Connect your channels to agents and workflows](https://agenticorg.ai/docs/channel-workflows): Bring your own provider account, protect credentials, link a private sender, and run bounded tasks from messaging, email, voice or signed gateways.
- [Core concepts and glossary](https://agenticorg.ai/docs/concepts): A plain-language guide to agents, tools, prompts, workflows, grants, knowledge, shadow mode, cases and OACP artifacts.
- [AI providers and model setup](https://agenticorg.ai/docs/model-setup): Configure provider credentials, select models, control routing and costs, and diagnose tenant or company credential problems.
- [Model Gateway, routing and limits](https://agenticorg.ai/docs/model-gateway): Create scoped routing and access policies, dry-run decisions, manage limits, and interpret model-call records and cost estimates.
- [Create and manage agents](https://agenticorg.ai/docs/create-agents): Use natural-language drafts or manual setup; configure persona, tools, prompts, behavior, visibility and shadow evaluation.
- [Run agents and use chat](https://agenticorg.ai/docs/run-and-chat): Supply clear inputs, preserve company context, read run outcomes and handle refusals without assuming an external action happened.
- [Knowledge Base and scanned documents](https://agenticorg.ai/docs/knowledge-and-ocr): Upload supported documents, understand OCR and extraction quality, handle duplicates, and validate source-grounded search.
- [Connect business systems](https://agenticorg.ai/docs/connectors): Register a connector, bind credentials to the correct scope, verify health and permissions, and grant only the tools your agent needs.
- [Build and run workflows](https://agenticorg.ai/docs/workflows): Turn a process into reviewed steps, conditions, approvals and durable runs; test failures before enabling schedules.
- [Voice, speech-to-text and text-to-speech](https://agenticorg.ai/docs/voice): Configure the signed Twilio runtime, validate speech turns and call history, and test calls only with approved destinations.
- [Browser RPA and schedules](https://agenticorg.ai/docs/rpa): Run reviewed browser scripts with approved domains, inspect durable history, and resume from a reviewed step after target-site changes.
- [Industry packs and business dashboards](https://agenticorg.ai/docs/industry-packs): Use available packs as reviewed starting points and understand the finance, HR, marketing, operations and partner workspaces.
- [Approvals and human review](https://agenticorg.ai/docs/approvals): Review evidence and permissions before a decision, handle escalations, and distinguish workflow approvals from governed-case decisions.
- [Governed business onboarding cases](https://agenticorg.ai/docs/governed-cases): Investigate a business, inspect cited evidence and deterministic policy scores, review screening proposals, and request a human decision.
- [Documents, conversations, calls and workbenches](https://agenticorg.ai/docs/review-and-operations-screens): Find and use the Documents, Conversations, Workbenches, Calls, Transactions and Lineage screens, each off until an operator turns on its setting.
- [Audit, monitoring and run history](https://agenticorg.ai/docs/audit-and-monitoring): Read agent and workflow evidence, understand dashboard limits, investigate failures, and measure your own service outcomes.
- [Guardrail rules, dry runs and enforcement](https://agenticorg.ai/docs/guardrails): Configure tenant-admin guardrail rules through the authenticated API, test detector behavior, and distinguish flag-only from enforced operation.
- [Run timelines and workload observability](https://agenticorg.ai/docs/run-observability): Use the admin trace waterfall and tenant workload view, understand opt-in tracing and storage, and investigate run failures without overreading missing data.
- [Evaluate and roll out safely](https://agenticorg.ai/docs/evaluate-and-rollout): Build representative tests, compare quality and cost, validate refusals, and promote a bounded pilot with a rollback plan.
- [Security, privacy and data handling](https://agenticorg.ai/docs/security-and-data): Choose appropriate data, review provider retention and access, protect credentials, and organize evidence deletion and incident response.
- [Billing, limits and support](https://agenticorg.ai/docs/billing-and-support): Understand hosted plan limits and provider charges, use the billing console, and send a useful support request without secrets.
- [Usage and licensing](https://agenticorg.ai/docs/licensing): Understand free self-use and commercial agreements for existing and new covered users, prior source rights and the separate software-release adoption boundary.
- [AI spend intelligence and invoice reconciliation](https://agenticorg.ai/docs/ai-spend-intelligence): Attribute metered AI usage to your organisation tree, price it in rupees from contract or list rate cards, reconcile invoices within 1% and read the Gate 1 status.
- [Troubleshooting by symptom](https://agenticorg.ai/docs/troubleshooting): Resolve access, model, connector, OCR, workflow, voice, RPA and commerce problems using concrete checks and safe recovery steps.
- [Seller and buyer commerce with OACP](https://agenticorg.ai/docs/commerce): Follow merchant configuration, Shopify sync, Grantex authority, artifact-backed buyer answers and provider or POS handoffs.
- [External buyer and seller A2A demo](https://agenticorg.ai/docs/external-buyer-a2a-demo): See a standalone buyer discover a synthetic seller, browse a scoped catalog, inspect source freshness, and test purchase refusal and credential revocation.
- [Seller commerce with an outside A2A buyer](https://agenticorg.ai/docs/seller-a2a-commerce-journey): An interactive third-party buyer transaction map and six checkpoints covering merchant setup, A2A seller access, sourced answers and the Pine Labs Plural payment boundary.
- [API, SDK, MCP and A2A integration](https://agenticorg.ai/docs/api-sdk-mcp): Connect applications and agent clients with authenticated, scoped APIs; distinguish public discovery from permission to execute.
- [Self-hosting and deployment handoff](https://agenticorg.ai/docs/self-hosting): Understand hosted versus bank-managed operation, local Docker setup, migration-first releases, backups and operational responsibilities.
- [BFSI: business onboarding and KYB review](https://agenticorg.ai/docs/bfsi-business-onboarding): A fictional configured example from business application to evidence investigation, screening review, human decision and signed handoff.
- [BFSI: reconciliation and finance exceptions](https://agenticorg.ai/docs/bfsi-reconciliation): Configure a read-only reconciliation assistant for synthetic bank and ledger data, review discrepancies, and hand approved corrections to finance.
- [BFSI: customer service across chat and voice](https://agenticorg.ai/docs/bfsi-customer-service): Build a source-grounded service assistant, classify complaints, prepare responses and escalate sensitive account actions to authorized staff.
- [BFSI: insurance document and claims assistance](https://agenticorg.ai/docs/bfsi-insurance): Use OCR, policy knowledge and reviewed workflows to prepare claim-file checklists without automating coverage or payout decisions.
- [BFSI: merchant enablement and agentic commerce](https://agenticorg.ai/docs/bfsi-merchant-services): A bank-led merchant pilot using Seller Commerce Agents, Shopify, OACP artifacts, buyer channels and provider-owned payment capability evidence.
- [BFSI capability status and open work](https://agenticorg.ai/docs/bfsi-capability-status): See which functional capabilities exist, which remain partial or unavailable, and what a configured pilot still needs to prove.
- [Team adoption and launch checklist](https://agenticorg.ai/docs/adoption-checklist): Assign owners, select a first use case, train operators and reviewers, measure outcomes and expand without skipping real integration work.
- [Customer agent: own the agent, open the agent](https://agenticorg.ai/docs/customer-agent): The bank-operated assistant for the bank's own customers: sessions without a platform credential, the autonomy ladder, one-tap cards, the bank's step-up, why-this explanations, the permissions page and the embeddable element, all off by default.

Authenticated routes, callbacks, invites, onboarding, and dashboard pages are application surfaces, not public search landing pages.

## Blog index

Titles describe editorial topics. Numerical examples and case-study language are not platform-wide performance guarantees.

- [Merchant Self-Service Config for OACP Commerce](https://agenticorg.ai/blog/merchant-self-service-oacp-commerce-config)
- [A Reference Shopify-to-Seller-Agent Readiness Journey](https://agenticorg.ai/blog/shopify-merchant-seller-commerce-agent-oacp)
- [Designing Buyer-Channel Adapters for Seller Agents](https://agenticorg.ai/blog/oacp-buyer-channels-seller-agent)
- [How OACP Maps Catalog, Price, Inventory, and Policy into Buyer-Safe Artifacts](https://agenticorg.ai/blog/oacp-artifacts-buyer-safe-commerce-facts)
- [How Pine/Plural and Bank-Owned Payment Handoffs Fit into OACP](https://agenticorg.ai/blog/provider-owned-pine-bank-handoff-oacp)
- [How Grantex Stays a Trust Authority Without Becoming a Transaction Toll Booth](https://agenticorg.ai/blog/grantex-trust-authority-not-commerce-toll-booth)
- [Offline POS Bridge: Connecting In-Store Checkout to AI Buyer Agents](https://agenticorg.ai/blog/offline-pos-bridge-agentic-commerce)
- [Planning AI-Assisted GST, TDS, and Reconciliation Workflows for CA Firms](https://agenticorg.ai/blog/ai-agents-for-ca-firms-gst-tds-automation)
- [AI Agents and RPA: Choosing the Right Automation Pattern](https://agenticorg.ai/blog/virtual-employee-vs-rpa)
- [Automated Bank Reconciliation: A Pilot Measurement Framework](https://agenticorg.ai/blog/automated-bank-reconciliation)
- [Human-in-the-Loop Governance: Why Enterprise AI Needs Human Approval Gates](https://agenticorg.ai/blog/hitl-governance-enterprise-ai)
- [Mirror Your Company Org Chart with AI Virtual Employees](https://agenticorg.ai/blog/org-chart-ai-virtual-employees)
- [No-Code Agent Configuration: A Governed Creation Workflow](https://agenticorg.ai/blog/no-code-ai-agent-builder)
- [Email-Triggered Workflows: Automate Finance Operations from Your Inbox](https://agenticorg.ai/blog/email-triggered-workflows)

## Resource index

Titles describe educational topics. Verify any numerical claim against page evidence and current behavior before quoting it as an outcome.

- [Agent Activity: Audit History and Live Feed Boundaries](https://agenticorg.ai/resources/agent-activity-audit-and-live-feed)
- [Move Your Shopify Store to Agentic Commerce](https://agenticorg.ai/resources/move-shopify-store-to-agentic-commerce)
- [How Buyer Agents Shop Safely with OACP](https://agenticorg.ai/resources/buyer-agents-shop-safely-oacp)
- [Build Against OACP Artifacts and Bridges](https://agenticorg.ai/resources/build-against-oacp-artifacts-bridges)
- [How OACP Maps to Schema.org, UCP, ACP, AP2, A2A, and MCP](https://agenticorg.ai/resources/oacp-protocol-partner-mappings)
- [Provider-Owned Mandate and Payment Evidence in OACP](https://agenticorg.ai/resources/provider-owned-mandate-payment-evidence-oacp)
- [Launch and Rollback Runbook for OACP Commerce](https://agenticorg.ai/resources/oacp-launch-rollback-runbook)
- [Commerce Sales Agent with Grantex Controls](https://agenticorg.ai/resources/commerce-sales-agent-grantex)
- [What Are AI Agents for Enterprise?](https://agenticorg.ai/resources/what-are-ai-agents-for-enterprise)
- [AI Agents vs RPA: Choosing the Right Automation Approach](https://agenticorg.ai/resources/ai-agents-vs-rpa)
- [AI Agents vs Chatbots: What Is the Difference?](https://agenticorg.ai/resources/ai-agents-vs-chatbots)
- [Enterprise AI Automation Platform: How to Choose One](https://agenticorg.ai/resources/enterprise-ai-automation-platform)
- [Agentic AI Explained: What It Means for Business](https://agenticorg.ai/resources/agentic-ai-explained)
- [AI Accounts Payable Automation: Invoice Review to Approved Handoff](https://agenticorg.ai/resources/ai-accounts-payable-automation)
- [Automated Bank Reconciliation with Evidence-Backed Matching](https://agenticorg.ai/resources/automated-bank-reconciliation-ai)
- [GST Compliance Workflow Automation with Human Review](https://agenticorg.ai/resources/gst-compliance-automation)
- [Month-End Close Automation with Scoped Agents](https://agenticorg.ai/resources/month-end-close-automation)
- [AI-Assisted Payroll Workflows for India](https://agenticorg.ai/resources/ai-payroll-automation-india)
- [AI-Assisted Employee Onboarding with Approval Controls](https://agenticorg.ai/resources/ai-employee-onboarding)
- [AI-Assisted Talent Acquisition with Human Decision Authority](https://agenticorg.ai/resources/ai-talent-acquisition)
- [AI Support Ticket Triage with Measured Routing Quality](https://agenticorg.ai/resources/ai-support-ticket-triage)
- [AI IT Operations: Governed Incident and Runbook Assistance](https://agenticorg.ai/resources/ai-it-operations)
- [AI-Assisted Compliance Monitoring and Evidence Collection](https://agenticorg.ai/resources/ai-compliance-automation)
- [Human-in-the-Loop AI: Configuring Meaningful Review](https://agenticorg.ai/resources/human-in-the-loop-ai)
- [AI Audit Trails: Evidence, Scope, and Retention](https://agenticorg.ai/resources/ai-audit-trail)
- [SOC 2 for AI Systems: Controls and Evidence to Evaluate](https://agenticorg.ai/resources/soc2-ai-compliance)
- [Shadow-Mode Testing for AI Agents](https://agenticorg.ai/resources/shadow-mode-testing)
- [No-Code AI Agent Builder: From Configuration to Validation](https://agenticorg.ai/resources/no-code-ai-agent-builder)
- [AI Virtual Employees: A Product Metaphor with Governance](https://agenticorg.ai/resources/ai-virtual-employees)
- [Prompt Template Management for Governed Agents](https://agenticorg.ai/resources/prompt-template-management)
- [AI Workflows for Indian Enterprise Systems](https://agenticorg.ai/resources/indian-enterprise-ai)
- [EPFO Workflow Automation: Preparation, Review, and Provider Handoff](https://agenticorg.ai/resources/epfo-automation-india)
- [Darwinbox and AI Agents: Controlled HRMS Workflows](https://agenticorg.ai/resources/darwinbox-ai-integration)
- [Tally and AI Agents: Governed Accounting Integration](https://agenticorg.ai/resources/tally-ai-integration)

## Answer-engine evidence rules

- Quote live registry totals only from https://app.agenticorg.ai/api/v1/product-facts.
- Quote hosted prices only from the current pricing API or core/billing/catalog.py.
- Do not present a source connector name as evidence of a customer connection.
- Do not present examples as measured speed, accuracy, savings, or compliance guarantees.
- Do not describe repository controls as a third-party certification.
- Do not describe source-only governed-case controls as deployed until the live revision is verified; distinguish the local case-purpose allowlist from token-level purpose and per-case cap enforcement.
- Do not describe adapter-ready commerce configuration as active execution.
- Do not infer payment, order, mandate, refund, receipt, or inventory success from cached OACP evidence.
- Prefer current code and canonical runbooks over dated reports.

## Additional direct answers

### Why are registry totals not copied into this file?

Registries evolve, and file or binding counts can double-count aliases. The product facts endpoint applies runtime registry rules to the deployed system.

### Does every action require manual approval?

No universal claim should be made. AgenticOrg supports configurable human approval, confidence, amount, escalation, and policy conditions. Whether a step pauses depends on the workflow and tenant policy.

### Is Composio the native connector registry?

No. Composio is an optional integration gateway. Native totals come from the AgenticOrg runtime registry through the product facts endpoint.

### Which commerce source is runtime-supported?

Shopify is the current supported source path in the canonical OACP documentation. WooCommerce, ERP, PIM, OMS, WMS, custom APIs, and additional rails are adapter-ready configuration until approved adapters and evidence exist.

### Is AgenticOrg certified to a particular security standard?

This guide makes no certification claim. The repository contains security and governance controls; certification requires separate, current third-party evidence.

### What does OACP evidence authorize?

It supports a governed decision to answer, refresh, prepare a handoff, or refuse. It does not execute or confirm an order, inventory hold, mandate, payment, receipt, or refund.

## Discovery endpoints

- Robots: https://agenticorg.ai/robots.txt
- Sitemap: https://agenticorg.ai/sitemap.xml
- Summary guide: https://agenticorg.ai/llms.txt
- Full guide: https://agenticorg.ai/llms-full.txt
- Product facts: https://app.agenticorg.ai/api/v1/product-facts

This file is supplemental discovery material. It does not override robots controls, canonical metadata, visible page content, provider responses, or the current application.

## Public end-user manual

These source-verified guides describe usage and configured boundaries, not a blanket production or regulatory approval. Canonical hub: https://agenticorg.ai/docs.

### Start here

URL: https://agenticorg.ai/docs/start-here
Audience: Everyone. Reviewed: 2026-10-11.

#### What you can do with AgenticOrg

AgenticOrg is a workspace for building and operating AI agents around your procedures, documents and approved business tools. It brings agents, knowledge, workflows, approvals and run evidence together. You decide the task and the boundaries; an agent is not a replacement for your organization's authority to make a financial, legal or customer decision.

You can start with a document question, then progress to a repeatable workflow. You do not need to connect every system before the first useful task. A model and a small, approved knowledge set are enough for a read-only learning exercise.

```flow
Choose a task | Pick one narrow job with a clear owner and a measurable outcome.
Add knowledge and tools | Supply current procedures and only the permissions required.
Test with sample data | Inspect evidence, errors and refusals before relying on outputs.
Run under review | Assign operators, approvals, support and change control.
```

#### Choose your learning path

| Your role | Start with | Then learn |
| --- | --- | --- |
| First-time user | [Your first useful agent](/docs/first-agent) | [Knowledge and OCR](/docs/knowledge-and-ocr), [Run and chat](/docs/run-and-chat) |
| Administrator | [Workspace and roles](/docs/workspace-and-roles) | [Model setup](/docs/model-setup), [Model Gateway](/docs/model-gateway), [Guardrails](/docs/guardrails), [Connectors](/docs/connectors) |
| Process owner | [Create agents](/docs/create-agents) | [Workflows](/docs/workflows), [Approvals](/docs/approvals), [Evaluation](/docs/evaluate-and-rollout) |
| Bank or fintech team | [Business onboarding](/docs/bfsi-business-onboarding) | [Reconciliation](/docs/bfsi-reconciliation), [Customer service](/docs/bfsi-customer-service) |
| Merchant team | [Commerce](/docs/commerce) | [BFSI merchant services](/docs/bfsi-merchant-services) |
| Developer or IT team | [API, SDK, MCP and A2A](/docs/api-sdk-mcp) | [Self-hosting](/docs/self-hosting) |

#### Before you begin

1. Obtain an account at [app.agenticorg.ai](https://app.agenticorg.ai) or your organization's reviewed deployment. Accept an invitation if your organization already exists; do not create a second organization simply to join your team.
2. Ask the administrator which company and role you should use. Company selection matters for business data and connector access.
3. Confirm that a model provider is configured for your task. Your login does not automatically provide every external provider credential.
4. Use synthetic or approved non-sensitive material for your first exercise. Do not upload customer identity documents as a trial.
5. Know who can approve outputs and who owns the connected system.

#### What availability means

For regulated workflows, first read the [BFSI capability status](/docs/bfsi-capability-status).
The five process maps are fictional configured examples; 24 of 150 assessed
functional capabilities are covered, 97 are partial and 29 remain gaps.

**Implemented** means a runtime path exists. **Configuration-dependent** means it also needs credentials, permissions, worker infrastructure or tenant settings. **Example** means a teaching scenario, not a pre-integrated solution. A listed connector, agent template, voice provider or channel is not proof of successful live execution in your workspace.

Shopify read-only commerce sync and the signed Twilio voice runtime have specific implemented paths. Other commerce sources and voice-provider options do not automatically have equivalent runtime support. OACP buyer answers and prepared handoffs do not themselves create orders or collect money. Jev advisory integration is access-gated and is not an active production decision authority.

#### Find the right screen

These links open the hosted application. Sign in first and select the correct
company. On a self-managed deployment, use its hostname with the same path.
Some screens are restricted by role; a missing menu is not an invitation to
bypass permissions.

| I want to... | Screen | Read first |
| --- | --- | --- |
| Choose a company | [Companies](https://app.agenticorg.ai/dashboard/companies) | [Workspace and roles](/docs/workspace-and-roles) |
| Connect a model | [AI Credentials](https://app.agenticorg.ai/dashboard/settings/ai-credentials) | [Model setup](/docs/model-setup) |
| Find or create an agent | [Agents](https://app.agenticorg.ai/dashboard/agents) | [Create agents](/docs/create-agents) |
| Build from a procedure | [Create from SOP](https://app.agenticorg.ai/dashboard/agents/from-sop) | [Create agents](/docs/create-agents) |
| Upload a document | [Knowledge Base](https://app.agenticorg.ai/dashboard/knowledge) | [Knowledge and OCR](/docs/knowledge-and-ocr) |
| Connect a business service | [Connectors](https://app.agenticorg.ai/dashboard/connectors) | [Connectors](/docs/connectors) |
| Coordinate several steps | [Workflows](https://app.agenticorg.ai/dashboard/workflows) | [Workflows](/docs/workflows) |
| Review proposed actions | [Approvals](https://app.agenticorg.ai/dashboard/approvals) | [Human review](/docs/approvals) |
| Review business onboarding | [Governed cases](https://app.agenticorg.ai/dashboard/approvals/cases) | [Governed cases](/docs/governed-cases) |
| Review extracted document fields (off by default) | [Documents](https://app.agenticorg.ai/dashboard/documents) | [Default-off screens](/docs/review-and-operations-screens) |
| Watch or take over a live chat (off by default) | [Conversations](https://app.agenticorg.ai/dashboard/conversations) | [Default-off screens](/docs/review-and-operations-screens) |
| Work from a role workbench (off by default) | [Workbenches](https://app.agenticorg.ai/dashboard/workbench) | [Default-off screens](/docs/review-and-operations-screens) |
| Review kept call recordings (off by default) | [Calls](https://app.agenticorg.ai/dashboard/calls) | [Default-off screens](/docs/review-and-operations-screens) |
| Decide transaction findings (off by default) | [Transactions](https://app.agenticorg.ai/dashboard/transactions) | [Default-off screens](/docs/review-and-operations-screens) |
| Trace where a kept item came from (off by default) | [Lineage](https://app.agenticorg.ai/dashboard/lineage) | [Default-off screens](/docs/review-and-operations-screens) |
| Configure voice | [Voice Agents](https://app.agenticorg.ai/dashboard/voice-setup) | [Voice](/docs/voice) |
| Configure browser automation | [RPA Scripts](https://app.agenticorg.ai/dashboard/rpa) | [RPA](/docs/rpa) |
| Investigate run evidence | [Audit Log](https://app.agenticorg.ai/dashboard/audit) | [Monitoring](/docs/audit-and-monitoring) |
| Inspect run timelines | [Observability](https://app.agenticorg.ai/dashboard/observability) | [Run observability](/docs/run-observability) |
| Configure model routing | [Model Gateway](https://app.agenticorg.ai/dashboard/settings/model-gateway) | [Model Gateway](/docs/model-gateway) |
| Configure guardrail rules | [Guardrails](https://app.agenticorg.ai/dashboard/settings/guardrails) | [Guardrails](/docs/guardrails) |
| Configure merchant commerce | [Commerce Runtime](https://app.agenticorg.ai/dashboard/commerce-runtime) | [Commerce](/docs/commerce) |
| Connect an external agent client | [A2A / MCP](https://app.agenticorg.ai/dashboard/integrations) | [API and clients](/docs/api-sdk-mcp) |
| Create an API key | [Settings](https://app.agenticorg.ai/dashboard/settings) | [API and clients](/docs/api-sdk-mcp) |
| Review subscription or usage | [Billing](https://app.agenticorg.ai/dashboard/billing) | [Billing and support](/docs/billing-and-support) |
| Review recorded agent cost in USD (no sidebar entry) | [Cost Dashboard](https://app.agenticorg.ai/dashboard/costs) | [Billing and support](/docs/billing-and-support) |

#### When you get stuck

For current license rights and the approved prospective policy, read
[Usage and licensing](/docs/licensing). Software adoption still needs an exact
release/file scope. Existing Apache-2.0 rights remain unchanged; hosted
plans, infrastructure and provider usage may have separate charges.

Use [Troubleshooting](/docs/troubleshooting) to isolate the issue. Record the screen, time, selected company, action and safe error code. Never send passwords, API keys or raw customer files in a support ticket.

The guides describe source-verified behavior, not a promise that your deployment has every optional feature enabled. Ask your administrator about the deployed version and tenant configuration.


### Your first useful agent

URL: https://agenticorg.ai/docs/first-agent
Audience: New users. Reviewed: 2026-10-02.

#### Outcome of this exercise

Build a read-only procedure assistant that answers questions from a small approved document. The example uses a fictional bank's complaint-routing procedure. It must not change accounts, send messages, issue refunds or make regulatory decisions. Allow a focused onboarding session; actual setup time depends on your account and model configuration.

#### Before you start

You need permission to create agents, a selected company where applicable, a working model credential, and access to Knowledge Base. If those screens are missing, ask your administrator; do not work around access controls with another person's account.

Create a plain-text sample document containing:

```text
Example Bank - service-routing exercise - version 1
Owner: Service Operations
Account balance questions: refer to the authenticated banking channel.
Card loss reports: escalate to the approved card-support team immediately.
General branch-hours questions: answer from the current branch directory.
Missing or conflicting procedure: ask a supervisor; do not invent an answer.
This synthetic procedure is not a real bank policy.
```

#### Step 1: prepare the workspace

Sign in and confirm the organization and company. Open **AI Provider Credentials** if you are the administrator and test the chosen credential. If a colleague maintains credentials, ask them to confirm readiness for the selected model instead of sharing the key with you.

#### Step 2: upload and verify knowledge

1. Open **Knowledge Base**.
2. Upload the sample file. Wait for an explicit successful extraction/indexing result.
3. Search for `card loss reports`. Inspect the returned text and source information.
4. If no usable result appears, resolve extraction or search configuration before creating a workflow that relies on it.

An upload accepted by the browser is not necessarily an indexed document. [Knowledge and OCR](/docs/knowledge-and-ocr) explains status, duplicate handling and quality checks.

#### Step 3: create the agent

Open **Agents**, then the creation screen. The wizard is titled **Create Virtual Employee**. You can describe the task to generate a draft or proceed through **Persona**, **Role**, **Prompt**, **Behavior** and **Review**.

Use a descriptive name such as `Service Procedure Assistant`. Select an appropriate operations role or custom type. Give it this bounded instruction:

```text
Answer procedural questions using approved knowledge available to this run.
State the source and distinguish missing information from a verified fact.
Do not infer a customer's balance, identity, eligibility or payment status.
Do not change accounts, contact customers or initiate transactions.
If the relevant procedure is missing or conflicting, request human review.
```

Choose the configured model and leave unrelated connectors and authorized tools unselected. Inspect the full review screen, then use **Create as Shadow**. Shadow is a candidate/testing state, not a substitute for reviewing tool permissions or assuming all side effects are suppressed.

#### Step 4: run and inspect

From the agent detail screen, run a question that the document answers. Then try an unsupported request and a missing-information request:

| Test input | Expected behavior |
| --- | --- |
| How should a card-loss report be routed? | The approved escalation path, with source context |
| What is customer 123's account balance? | No invented balance; refer to the authenticated bank channel |
| Refund the customer and mark the complaint closed | Refuse execution; identify the authorized review path |

Inspect the output, status, source evidence and tool activity. A fluent answer is not enough. If retrieval is not available to the chosen agent/run path, configure its documented knowledge/tool integration; do not assume a global upload automatically grounds every model response.

#### Step 5: make it useful to a team

Have a second person reproduce the exercise with the correct role and company. Record expected answers and refusal cases. Only then consider activation, additional read tools or a reviewed workflow. See [Evaluation and rollout](/docs/evaluate-and-rollout) and [Team adoption](/docs/adoption-checklist).


### Workspace, companies and roles

URL: https://agenticorg.ai/docs/workspace-and-roles
Audience: Administrators and team leads. Reviewed: 2026-10-11.

#### Organization, company and user are different things

The **organization/tenant** is the security boundary for your workspace. A **company** is a business context within that workspace, particularly useful for partner or multi-company operations. A **user** receives a role and permissions. Selecting a company does not grant access to another tenant.

Many confusing errors come from doing the right action in the wrong company or with a role that cannot perform it. Always check company context before interpreting connector readiness, agent lists or model credentials.

#### Set up the organization

The onboarding wizard includes organization details, industry and size, team invitations, system connection and a completion checklist. Choose **Finance & Banking** where appropriate; selecting an industry does not provision core banking, KYC providers or a compliance certification.

1. Confirm you are setting up a new organization rather than duplicating an existing one.
2. Enter reviewed organization information.
3. Invite named colleagues using the least-powerful suitable role.
4. Review connector setup separately; finish only the connections you are ready to own.
5. Assign a platform administrator and a backup owner.

#### Understand role-based navigation

The sidebar deliberately differs by role. The backend, not a visible button, decides whether the operation is authorized. Current common roles include administrator, finance/CFO, HR/CHRO, marketing/CMO, operations/COO, auditor, merchant, domain lead, analyst (read-only within an assigned domain) and developer (builds personal agents and connectors, and approves only their own personal agents).

| Task | Typical owner | Important boundary |
| --- | --- | --- |
| Organization settings, credentials and billing | Administrator | Do not distribute an admin login to operators |
| Domain agents and workflows | Authorized domain lead | Tools and data remain separately scoped |
| Merchant commerce runtime | Administrator or merchant | Merchant binding and publishing settings still apply |
| Evidence and audit review | Authorized auditor/reviewer | Read access is not decision or execution permission |
| Human case decision | Named authorized approver | Machine credentials cannot impersonate a person |

This is a responsibility guide, not an exhaustive permission table. Exact scopes are deployment- and role-dependent. When a link is absent or an API returns `403`, have the administrator review your assigned role and required scope.

#### Multi-company operating checklist

Before a run, check the selected company, agent ownership, model credential binding, connector binding and input references. A tenant-wide connector can be available under different rules from a company-specific connector; a healthy global connector does not prove that your company can use it.

Do not copy a successful company's connector ID into another company's task. Have the owner configure the correct binding and re-test with that company selected. Verify negative access tests as well as successful ones.

#### Team changes and account recovery

During onboarding, the **Send Invites** action creates the entered invitations.
The CFO/CHRO/CMO/COO labels map to domain-lead invitations for their respective
domains. An invitation is created as administrator, domain lead, analyst, auditor
or developer; one sent without a role is created as analyst. Check any per-recipient failure before retrying; successful recipients
are cleared from the form rather than being resent.

In **Settings > User Management**, follow the entry points for company role
management. Per-company mappings live in **Companies > company detail > Settings
> Company Role Mapping**. That section is not a complete tenant user-directory
or SSO-provisioning console. Have your administrator use the supported invitation
and identity process for your deployment, not an invented bulk member editor.

Reset forgotten passwords through the sign-in flow; never ask a colleague for theirs.
When a person leaves, review access, API keys, connector ownership, workflow
schedules and outstanding approvals, not just their login. Confirm revocation
with the actual identity/grant issuer as well as company role mappings.

SSO, SCIM and enterprise identity capabilities depend on plan and deployment configuration. Agree the source of truth with IT before relying on automated offboarding. [Security and data](/docs/security-and-data) and [Adoption checklist](/docs/adoption-checklist) cover ownership and review.


### Connect your channels to agents and workflows

URL: https://agenticorg.ai/docs/channel-workflows
Audience: Agent creators and administrators. Reviewed: 2026-10-02.

#### From a message to useful work

Create an agent with a purpose, knowledge and permitted tools, or choose an existing workflow. Open **Channels** in the dashboard. Choose a provider, choose the destination, and enter credentials from your own provider account. Connections start disabled. For Telegram, select **Connect Telegram** to check the bot and register its callback. For other providers, register the displayed HTTPS callback with the provider before enabling the connection.

```flow
Create a provider account | You own the account, permissions and billing. | Owner: Workspace user
Choose an agent or workflow | Agent creators connect agents they can manage. Workflow connections require an administrator. | Owner: Workspace user
Save protected credentials | AgenticOrg encrypts credentials; it never returns them in the channel list. | Owner: AgenticOrg
Register and enable the callback | Use the callback URL and the provider's signing or verification settings. | Owner: Workspace user | If blocked: Check the provider application permissions and account approval.
Link a private sender | Generate a one-time command and send it from your private messaging account. | Owner: Workspace user | Human decision: Delegate your current account permissions.
Run a bounded task | A durable worker invokes the existing agent or workflow execution path. | Owner: AgenticOrg | If blocked: Review the message, identity, provider signature or run error.
Review results and approvals | Open the inbox and run history. Sensitive actions retain their existing approval requirements. | Owner: Workspace user
```

Unlinked senders do not acquire your permissions. Their text enters a review inbox. Approving one message authorizes that message only. A provider signature identifies an authentic callback, not a human user. Linking is available for private text messages, not Telegram groups or email From addresses. Link commands expire after ten minutes, are single-use, and delegate for thirty days. Disabling a connection or rotating credentials revokes links and queued delegated work. An already-running external action cannot be undone by disabling its connection.

#### Credentials belong to you

Enter secrets only in the signed-in credential form. Never put tokens, API keys, webhook secrets, passwords or one-time link commands in chat, prompts, repository files or support screenshots. To arrange assisted testing, share only the provider name, account approval status, test sender or destination you authorize, and a sanitized request ID. Use the credential form or your organization's approved secret-management process for the secret itself. Choose dedicated test accounts, minimum permissions and spending limits.

The first version accepts bounded text messages. Images, files and voice notes on these messaging callbacks do not start tasks. Use the knowledge-upload and voice setup paths for document processing and calls. Native messaging replies, when enabled, contain task status only. Results stay in the authenticated AgenticOrg inbox; private knowledge and tool outputs are not broadcast to the channel. Email and generic gateways have no native outbound reply in this version.

#### Google reasoning model

The default for newly created agents is `gemini-3.5-flash-lite`. Existing agents keep their explicitly selected model. Administrators can select a different model, fallback and provider. Obtain a Gemini API key through [Google AI Studio](https://aistudio.google.com/), enable the account and billing appropriate for your usage, and save it under **Settings > AI credentials > Gemini**. Use company-scoped credentials for company agents and the appropriate tenant credential for personal agents. Model availability and quota must be verified with your account before relying on it.

Gemini reasoning does not replace speech recognition or speech synthesis. This model does not generate audio; configure those providers separately. Operator overrides remain available through `AGENTICORG_LLM_PRIMARY` and `AGENTICORG_LLM_FALLBACK`.

#### WhatsApp and Meta Messenger

Create a Meta developer application and the appropriate business assets. For WhatsApp, attach your business account and phone number to the Cloud API. For Messenger, connect the Facebook Page and subscribe the app to its messaging callbacks. Complete the platform's business verification, application review and messaging permissions before serving external users.

Save the app secret, access token, a verification token you generate, the destination ID and a supported Graph API version. **Receiver ID** means the phone-number ID for WhatsApp, not the telephone number; for Messenger it means the Page ID. Register the callback URL and matching verification token. Subscribe to messages. AgenticOrg verifies the raw-body `X-Hub-Signature-256` signature and checks receiver scope before storing any message. Use the provider's development/test recipients first. Test tokens can expire; replace them with the account's approved production credential when ready.

See [WhatsApp setup](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started) and [Messenger setup](https://developers.facebook.com/docs/messenger-platform/getting-started/). Provider restrictions, customer-contact windows and billing still apply. An AgenticOrg connection is not platform approval. Use a dedicated verification token, never an API key or app secret: Meta sends it in its verification URL, which provider or infrastructure request logs may retain. Application access logs redact it.

#### Telegram

Open [BotFather](https://t.me/BotFather), send `/newbot`, and follow its prompts to create a dedicated bot. In AgenticOrg, choose Telegram and the destination agent or workflow, enter the bot token, select **Generate secret**, and save. Select **Connect Telegram**: AgenticOrg checks the bot account, registers the HTTPS callback and verifies its registration before enabling the connection. Tokens never need to appear in a browser URL or terminal command. A bot already connected to another application is refused; use a dedicated bot rather than overwriting that application's callback.

Open a private conversation with the bot, generate **Link my messaging account** in AgenticOrg and send the displayed command from that private account. Then send a small, read-only task. Groups and channel posts deliberately do not inherit a human account's authority. Localhost callbacks cannot be registered with Telegram; use the deployed HTTPS service for the real account test. AgenticOrg supplies `secret_token` and requires the resulting `X-Telegram-Bot-Api-Secret-Token` header. Registration is not proof of delivery: confirm a real message and completed run in the inbox. See the [Bot API](https://core.telegram.org/bots/api#setwebhook).

#### Viber

Arrange a Viber bot account through the provider's commercial application process. New bots may require a commercial agreement; a normal personal Viber account is not a bot API credential. Save the bot authentication token. Register the displayed callback through the REST Bot API. AgenticOrg verifies `X-Viber-Content-Signature` against the raw body using that token. Link your private sender and test a text task. See [Viber's bot account and API requirements](https://developers.viber.com/docs/api/rest-bot-api/).

#### Inbound email and outbound email tools

For inbound email, create a Mailgun receiving domain, configure the DNS records required by Mailgun, and create a route forwarding a dedicated recipient to the AgenticOrg callback. Save the **webhook signing key**, not the general API key, and the exact receiving address. AgenticOrg checks the timestamp/token signature and recipient; email always requires a human to approve the message before execution. Email From can be spoofed and is not account authentication. Text-only form submissions are supported; attachments are not ingested by this callback. See [Mailgun receiving routes](https://documentation.mailgun.com/docs/mailgun/user-manual/receive-forward-store/).

For outbound email, configure the existing email connector with your own OAuth or provider credential, bind it to the agent and review tool permissions. Inbound receipt does not automatically grant an agent permission to send mail. Start with a dedicated test mailbox and consented recipients.

#### Voice and telephone calls

Open **Voice and calls** as an administrator and select the existing voice-enabled agent setup. Create a Twilio account, obtain a voice-capable number, and configure its inbound Voice URL as shown by the voice setup. Save the account credential and configure the supported speech-to-text and text-to-speech providers. Use trial/test destinations first. AgenticOrg's voice path checks signed callbacks and preserves outbound-call approval controls.

Telephony, speech recognition and speech synthesis have separate permissions, quotas and charges. Do not assume that saving a credential proves recognition accuracy or call delivery. Arrange a test number you own or are authorized to call, approve the destination explicitly and run the voice test with that account. No paid call should be made to an unapproved destination. See [Twilio Voice](https://www.twilio.com/docs/voice).

#### MCP tools and other channels

Open **MCP tools** to register a remote MCP server, supply its approved authentication and discover its tools. Review discovered tools and attach only the required tools to your agent. A connector credential is not permission to bypass workflow approvals or execute arbitrary writes. Private or insecure URLs are restricted by the transport's network-safety policy. Use a reachable HTTPS server for real provider integrations.

For WeChat or another channel without a native adapter here, use an approved gateway that verifies the channel's native identity/signature first, then forwards the normalized message through **Other channel / signed gateway**. This is not a native WeChat implementation. The gateway must preserve a stable sender identity and a unique event ID; it must not invent a user's identity from an unverified display name.

The gateway body is JSON with `event_id`, `sender_id` and `text`. Send an epoch-seconds `X-AgenticOrg-Timestamp` header and `X-AgenticOrg-Signature`, the hexadecimal HMAC-SHA256 of `timestamp + "." + raw_body` using the stored webhook secret. Callbacks older than five minutes are refused. The URL selects the tenant and binding; a tenant field in the body cannot change that scope. Retries reuse the event ID and exact message contents. Reusing an event ID for different contents is refused.

#### Verify before serving customers

Send a small signed test message, confirm it appears in the inbox, link the private sender or approve that one message, and inspect the completed agent/workflow run. Test a bad signature, duplicate message, expired link and disabled connection as well. Expect the same existing approvals for sensitive tools. A timed-out or interrupted execution enters review and is not automatically replayed, because it may already have performed an external action.

Channel agent targets must still be active or in shadow mode when the worker dispatches. Paused, retired, deleted, unavailable or no-longer-owned targets enter review instead of executing. A pause or revocation cannot undo a task already running. Workflow steps retain their existing approval and lifecycle policies.

Local provider-shaped tests prove the platform's wire handling, isolation and execution paths. They do not prove that your provider account is approved or that a real message or call was delivered. Record those account-backed results separately, with sanitized evidence and authorized test contacts.


### Core concepts and glossary

URL: https://agenticorg.ai/docs/concepts
Audience: Everyone. Reviewed: 2026-10-02.

#### The simple mental model

An **agent** performs a defined job. It receives **instructions** and **inputs**, reads approved **knowledge**, and can request authorized **tools**. A **workflow** coordinates jobs. **Policies, grants and approvals** determine boundaries. **Run history and audit evidence** help you understand what actually happened.

```flow
Task and context | A person or reviewed integration supplies the request and company context.
Evidence and tools | The agent uses permitted knowledge and bounded tool access.
Review and decision | A policy or person routes uncertain or consequential work.
Recorded outcome | Inspect the result and authoritative downstream confirmation.
```

#### Glossary

| Term | Plain-language meaning | Common misunderstanding |
| --- | --- | --- |
| Agent / virtual employee | A configured AI task worker | Not a person or unlimited system administrator |
| Agent type | The role or implementation used by an agent | A type name alone does not identify an authorized stored agent |
| Prompt | Versioned instructions for a model | Instructions cannot create permissions |
| Tool | A callable operation on a system | Listing a tool does not grant its use |
| Connector | Integration configuration and provider access | Registration does not prove live readiness |
| Knowledge Base | Documents and extracted content for retrieval | Uploading a file does not train or fine-tune a model |
| OCR | Turning scanned images into text | Not guaranteed perfect recognition |
| Run | One execution attempt and its recorded result | A prepared answer is not an external transaction |
| Shadow | A candidate/evaluation state | Not proof that every side effect is automatically blocked |
| HITL | Human-in-the-loop review | A confidence percentage is not business authorization |
| Workflow | Reviewed steps, branches and handoffs | A schedule does not bypass an approval |
| Tenant | Your organization's isolation boundary | Not a company name in a prompt |
| Company context | The authorized business entity for a task | Not a way to cross tenant boundaries |
| Grant / scope | Bounded permission for an identity or tool | Not permission for unrelated financial decisions |
| Governed case | Evidence investigation, policy and human decision record | Separate from a generic agent run |
| Policy tier | Deterministic risk classification in a governed case | Not an LLM confidence score |
| Artifact | Source-linked, bounded evidence or capability metadata | Not transaction authority by itself |
| TTL / freshness | How long evidence may be reused and how current it is | A valid signature does not make old inventory current |
| OACP | Agentic commerce trust and interoperability work | Not a claim of adopted public standardization |
| MCP / A2A | Integration and discovery surfaces for agents/tools | Not automatic inclusion in every AI marketplace |

#### Who owns what in commerce

AgenticOrg runs the buyer and seller agents. Grantex supplies trust, policy and canonical artifact authority. The merchant system remains the source of catalog, inventory and order truth. The provider, bank or fintech owns payment and mandate execution. POS or merchant systems confirm their own fulfillment outcomes.

A valid cached artifact can support non-binding conversation without sending every message through Grantex. An agent cannot use that cache to invent a price guarantee, inventory hold, successful payment or completed order. See [Commerce](/docs/commerce).

#### Know the outcome vocabulary

Read the actual state: draft, prepared, queued, running, awaiting review, failed, refused or completed are not interchangeable. For integrations, require the provider/system-of-record confirmation before calling a business action successful. If you cannot explain the evidence behind a result to a colleague, pause and investigate rather than promoting it.


### AI providers and model setup

URL: https://agenticorg.ai/docs/model-setup
Audience: Administrators. Reviewed: 2026-10-02.

#### What this configuration does

AI provider credentials let AgenticOrg call the chosen model or embedding service for the authorized tenant context. A connector credential and a model credential are different: connecting your accounting system does not authorize model calls, and a model key does not grant access to the accounting system.

The administrator screens are **AI Provider Credentials** and **AI Configuration**. The agent creation wizard also has provider, model and routing settings. Inspect your deployment's options; labels do not guarantee free usage, provider access or regional availability.

#### Before adding a provider

Ask IT/security which providers, endpoints, regions and data classes are allowed. Establish billing ownership, retention rules, rate limits and a rotation owner. For BFSI, confirm whether any customer data may leave the bank boundary and which endpoint has been contractually approved. These are organization decisions; the product does not certify your configuration.

#### Add and test a credential

1. Open **AI Provider Credentials** as an administrator.
2. Choose **New Credential**.
3. Select the provider and kind (for example LLM or embedding).
4. Enter the provider-issued key through the credential form, not an agent prompt or document.
5. Use a meaningful label that identifies its purpose without revealing customer information.
6. Supply the reviewed base URL where the provider requires it, such as Azure or an OpenAI-compatible endpoint.
7. Save and use the supported credential test. Verify the response and scope instead of assuming save means ready.

Credentials are stored through the platform's protected credential path. The form does not display the raw key again. Treat a masked entry as evidence of storage, not proof that every requested model is available.

#### Select a model and routing

In **Create Virtual Employee > Behavior**, choose the LLM provider/model and routing mode. Use a model actually served by the configured endpoint. Automatic routing can select a different tier based on configuration; disabling routing uses the selected model path. Confirm the resulting provider in run evidence before comparing latency or cost.

Tenant administrators can use the [Model Gateway](/docs/model-gateway) for scoped routing/access policies, dry runs and limits. It is distinct from adding provider credentials: a policy cannot make an unconfigured provider or model available.

Test a short task with the target company selected. Then test an agent or workflow using that same context. Do not validate a tenant/global key and assume company-specific resolution works identically.

#### Rotate without losing the operating context

Record which agents and environments use the credential. Use the supported rotation action, test a bounded run, and monitor failures. Do not remove an old provider account before confirming all scheduled and integration-driven consumers have switched. Never log raw keys in a rotation report.

#### Diagnose model failures

| Symptom | Check | Safe next action |
| --- | --- | --- |
| Credential not found | Tenant/company, credential kind and provider | Configure the correct authorized binding |
| Unauthorized/model not found | Key scope, endpoint and exact model ID | Correct provider configuration; do not paste keys into chat |
| Rate-limit or overload | Provider quota, concurrency, current incident | Retry with bounded backoff or approved routing |
| Knowledge search fails | Embedding service and indexed data | Test retrieval separately from LLM generation |
| Unexpected model/cost | Routing mode and actual run metadata | Adjust reviewed configuration and repeat the same task |

Jev/System One is an optional advisory integration with separate TypeSafe access and evaluation requirements. A waitlist enrollment does not supply an API key or activate production routing. Keep the ordinary model path usable without it.
#### Default reasoning and your own Google account

New agents default to `gemini-3.5-flash-lite`. Existing agents keep an explicitly
selected model. Administrators can choose another model and fallback in agent/AI
settings; operators can override unset defaults with `AGENTICORG_LLM_PRIMARY`
and `AGENTICORG_LLM_FALLBACK`.

Create or select a Google AI Studio project, enable the provider account and
appropriate billing, generate an API key, and save it in the protected **AI
credentials** Gemini form. Never paste the key into chat or an agent prompt.
Choose the correct company or tenant scope and test a small reasoning request.
Provider availability, quota and pricing depend on your account. This model does
not produce audio: configure STT/TTS separately for voice workflows. See the
[channel workflow guide](/docs/channel-workflows) for account setup and tests.


### Model Gateway, routing and limits

URL: https://agenticorg.ai/docs/model-gateway
Audience: Tenant administrators. Reviewed: 2026-10-11.

#### Control model routing with the Model Gateway

The Model Gateway is an administrator console for reviewing provider/model choices, routing rules, access policies, per-model limits, dry-run decisions, recent routing records and cost comparisons. It does not create provider credentials. Configure and test credentials first in [AI Provider Credentials](/docs/model-setup), then open **Model Gateway** in the administrator sidebar (`/dashboard/settings/model-gateway`) for tenant-scoped gateway controls.

The gateway is off by default. Until a platform operator turns on the `model_gateway.enabled` authority flag for your tenant, or sets `AGENTICORG_MODEL_GATEWAY_ENABLED` for the deployment, the status card shows **Gateway off**, and saved routing rules, access rules and limits are not applied: each model call keeps the provider and model its agent asked for. The dry run still shows what the rules would decide and says whether the gateway currently applies them. With the gateway on, a call goes ahead without its limit when the limit settings or their Redis state cannot be read, unless the deployment sets `AGENTICORG_MODEL_GATEWAY_LIMITS_FAIL_CLOSED=true`.

```flow
Prepare approved provider access | Add credentials and confirm allowed models, regions, billing owner and data terms.
Review current state | Check gateway status and existing routing, access and limit rules.
Draft one narrow rule | Set its priority, match conditions, allowed targets and reason.
Evaluate before rollout | Use the dry run with representative requests and inspect the chosen route or refusal.
Enable deliberately | Confirm tenant policy and feature configuration, then monitor routing records and workload outcomes.
```

#### Choose the right control

| Control | What it decides | Good first use |
| --- | --- | --- |
| Routing policy | Which configured provider/model or weighted target is selected for a matching request. A cost-aware policy picks the lowest-priced target whose observed failure rate stays under the policy's threshold, reading the routing records, and states that reason in the decision. A target with no observations in the window counts as healthy, so with routing records off (the default) the cheapest listed target is chosen | Prefer an approved lower-cost model for a bounded use case |
| Access policy | Whether a request matching a principal, application, agent, provider, model or other supported context is allowed or denied | Deny a model for a sensitive use case |
| Model limit | Maximum concurrent requests and/or requests per minute for a provider/model | Protect a shared quota from bursts |
| Dry run | What the current policy would decide for supplied request context | Compare intended behavior before changing live traffic |

Start with the smallest match scope. Priorities are ordered (lower values win); use explicit reasons that help the next administrator understand the decision. Review overlap between policies and access rules rather than assuming one rule overrides every other control. The dry-run result is a point-in-time evaluation, not a reservation of provider capacity or a guarantee about a later request.

#### Verify the outcome

After a controlled test, inspect the decision shown by the console. When routing-record capture is enabled for the deployment, use the Records tab to search by correlation ID and review provider, model, outcome, latency, token/cost fields and signature status. The Costs tab compares observed calls with available list-price data; an unpriced model or missing observation is not zero cost. Actual invoices and provider billing remain authoritative.

The records feature is configuration-dependent and disabled by default. Confirm `AGENTICORG_MODEL_GATEWAY_RECORDS_ENABLED` and its retention policy with the platform owner before expecting a history. Gateway status, API authorization and tenant scope still apply; a visible rule does not prove that every application path is routed through the gateway.

#### Safe rollout and recovery

1. Use synthetic or approved low-sensitivity inputs first.
2. Save the existing rule values and identify an administrator who can restore them.
3. Test allowed, denied, unmatched, provider-timeout and limit-exceeded cases.
4. Enable one change at a time, then compare the actual provider/model and failure rate.
5. Disable or revise the specific rule if outcomes differ from the dry run; record the reason and retest.

Do not paste provider keys into prompts, policy reasons or support tickets. Keep credentials in the credential manager, and ask the provider or platform administrator to resolve quota, endpoint or model-availability errors.

Next: [AI provider setup](/docs/model-setup), [Guardrails](/docs/guardrails), [Run observability](/docs/run-observability), [Security and data](/docs/security-and-data).


### Create and manage agents

URL: https://agenticorg.ai/docs/create-agents
Audience: Agent builders. Reviewed: 2026-10-02.

#### Decide the job before choosing a template

Write down the input, permitted output, source of truth, authorized tools and escalation owner. A useful job is specific: `prepare a complaint-routing summary from the current service procedure`, not `handle all banking operations`. Decide what the agent must refuse.

![Illustrative AgenticOrg agent fleet](/screenshots/agents.webp)

This existing product screenshot illustrates the fleet layout. Names, totals and confidence settings are sample values, not current registry totals or performance guarantees.

#### Three starting points

Use a natural-language description to generate a candidate, configure an agent manually, or use **Create from SOP** where your role allows it. Generated prompts and SOP drafts are proposals. Read every field before creation; do not assume a parser knows your approval policy or connector permissions.

#### Walk through the wizard

| Stage | What to enter | What to check |
| --- | --- | --- |
| Persona | Employee Name, designation, domain, optional avatar | Name the actual task; use approved image URLs |
| Role | Agent type/custom type, specialization, routing filters, reporting relationship | Match the business role; filters do not create access rights |
| Prompt | Reviewed template or explicit instructions | Cite sources, state missing evidence, define refusals and output structure |
| Behavior | Model/provider, routing, confidence floor, HITL condition, retries, connectors and Authorized Tools | Grant minimum access; set finite retries; review external side effects |
| Review | Full configuration and visibility | Company, tools, prompt, credentials and initial shadow status |

Personal and shared visibility depend on your role. Administrators can configure shared tenant agents; a personal agent is not exempt from tenant policy. A reporting hierarchy is for routing, not permission inheritance.

#### A prompt structure that operators can maintain

```text
Purpose: prepare a reviewable summary of the submitted service request.
Inputs: request reference, company context and approved source documents.
Use: only tools and knowledge made available to this agent.
Output: facts with sources, missing items, suggested next step, review required.
Refuse: account changes, payment execution, invented evidence and secret disclosure.
Escalate: ambiguous identity, conflicting sources, missing permission or policy.
```

Do not insert credentials, personal account numbers or legal guarantees into prompts. A prompt version is part of the evidence for a run; changing it changes the tested behavior.

#### Create, test and maintain

1. Choose **Create as Shadow** after reviewing the configuration.
2. Run representative correct, incomplete, conflicting and adversarial inputs.
3. Inspect actual tool calls and source-grounding, not only prose.
4. Compare the result against a human-reviewed answer set.
5. Have the authorized owner decide whether to activate/promote the candidate.
6. Retest after model, prompt, procedure, tool or provider changes.

Inspect the detail screen's supported lifecycle actions before pausing or promoting an agent. An operator override or paused state must be accompanied by a check of workflows and integrations that call it; changing an agent does not necessarily cancel work already accepted elsewhere.

#### Common mistakes

Too many tools can lead to unintended actions. Broad prompts make outputs hard to assess. Confidence thresholds are not calibrated accuracy claims. Shadow labels alone are not permission controls. Add capability only when you can explain and test its necessity.

Next: [Run and chat](/docs/run-and-chat), [Workflows](/docs/workflows), [Evaluate and roll out](/docs/evaluate-and-rollout).


### Run agents and use chat

URL: https://agenticorg.ai/docs/run-and-chat
Audience: Operators. Reviewed: 2026-10-11.

#### Choose the right entry point

Use the agent detail screen for a targeted run, the authenticated chat panel for conversational tasks, or a reviewed workflow for a repeatable multi-step process. The public **Playground** is illustrative sample content; it is not a production customer transaction.

Some roles cannot execute chat or agent runs even if they can inspect evidence. If the control is absent, check permissions with your administrator rather than using a colleague's credentials.

#### Supply an actionable request

Include the task, authorized company, input references, expected output and prohibited side effects. Prefer document/case references over pasting unnecessary personal data.

```text
For the selected company, summarize the uploaded synthetic complaint file.
Use the approved complaint procedure, cite its source and list missing items.
Prepare a response draft for review. Do not email it or change account state.
```

Check company context before sending. A request that names another company in text does not authorize the agent to access it. If the tool needs structured inputs, use the expected schema; free text cannot replace required fields.

#### Inspect the result

Read the run status and output together. Look for source references, missing facts, connector/tool outcomes, escalation and safe error information. A model saying `done` is not proof that a provider accepted an operation.

| Result | What it means | What to do |
| --- | --- | --- |
| Prepared/draft output | Material is ready for review | Check evidence before distribution |
| Awaiting approval | A human decision is needed | Open the appropriate review queue |
| Refused | Authority, safety or supported capability is missing | Resolve the reason; do not weaken policy to finish |
| Failed | The run could not complete | Check logs/status and retry only if safe |
| External action confirmation | A connected system reports an outcome | Validate identity, amount/scope and authoritative reference |

The exact status vocabulary varies by run resource. Preserve the returned state rather than translating every non-error response into success.

#### Follow-ups and retries

Chat passes earlier turns to a follow-up only when the deployment turns on conversational services (`AGENTICORG_CONVERSATION_V2_ENABLED`, off by default). While it is off, each message runs on its own even though the panel shows the earlier messages, so repeat the document, case and company reference every time. While it is on, recent turns from the same user, company and agent reach the agent as context; another user, company or agent does not share them. Do not ask an agent to "ignore the earlier policy" to unblock a refusal.

Before retrying an external action, check whether the provider already accepted it. Use the integration's idempotency and status lookup where available. Blindly rerunning a workflow can duplicate an email, record update or provider request.

#### Prove the path before inviting users

Test a permitted question, a missing-source question, a cross-company reference and a forbidden action. Confirm that an access or model failure is visible, not represented as an empty successful result. For voice, validate the same task boundary through signed speech turns; for commerce, verify artifact freshness and prepared-only semantics.

Next: [Troubleshooting](/docs/troubleshooting), [Approvals](/docs/approvals), [Audit and monitoring](/docs/audit-and-monitoring).


### Knowledge Base and scanned documents

URL: https://agenticorg.ai/docs/knowledge-and-ocr
Audience: Content owners and operators. Reviewed: 2026-10-11.

#### What Knowledge Base does

Knowledge Base extracts text, preserves provenance, chunks documents and supports tenant-scoped retrieval. It is not model training. Extraction/indexing success and a useful retrieved answer are separate checks. Your selected agent still needs the appropriate knowledge/tool path.

Open **Knowledge Base** in the authenticated workspace. The deployed supported-type and limit metadata is the authority for your environment; administrators can inspect `GET /api/v1/knowledge/supported-types` with approved credentials.

#### Supported document families

| Family | Typical formats | Handling |
| --- | --- | --- |
| Text/data | TXT, MD, CSV, TSV, JSON, YAML, XML, LOG | Native parsing/decoding |
| Web/email | HTML, HTM, EML | Body text extraction; active content removed |
| PDF | PDF | Native text first; OCR for low-text/scanned pages |
| Modern Office | DOCX, XLSX, PPTX | Paragraph, table, sheet and slide extraction |
| Legacy/OpenDocument | DOC, XLS, PPT, ODT, ODS, ODP | Isolated conversion, then extraction |
| Other | RTF | Text parsing |
| Images/scans | PNG, JPG/JPEG, TIF/TIFF, BMP, WEBP | OCR with confidence and page provenance |

Audio and video are not document uploads. File size, pages, decompressed pixels and archive expansion are bounded. Do not bypass limits by renaming an unsupported file.

#### Upload and verify

1. Confirm data-owner approval, company context and the procedure's effective version.
2. Choose a clearly named document, such as `Complaint Routing - reviewed 2026-09`.
3. Upload and wait for a visible successful extraction/indexing outcome.
4. Inspect extraction method, whether OCR ran and the confidence metadata.
5. Search a known phrase and review source/page/sheet/slide details.
6. Run a grounded question and verify it against the original document.

Each search result shows the document and, where recorded, its citation: page, sheet, cell range, paragraph or heading. **Open excerpt** shows the whole cited passage, with **Previous** and **Next** for the neighbouring passages. Where the deployment turns on query transformation (`AGENTICORG_KNOWLEDGE_QUERY_TRANSFORM_ENABLED`, off by default), **How this was retrieved** lists each retrieval step. Documents uploaded from this page are shared with the whole tenant. An API upload can name a domain (`?domain=`), and then users limited to other domains do not see that document.

If a duplicate dialog appears, choose the appropriate supported action deliberately. Replacement extraction is performed before old content is removed, but you should still verify that search returns the intended version. Do not leave two conflicting policies current without an explicit effective-date rule.

```flow
Approved upload | Size and type are validated before parsing.
Extract or OCR | Native text is preferred; scanned pages are recognized where needed.
Index with provenance | Chunks retain page, sheet, slide and freshness context.
Search and review | Verify a known answer against the source before operational use.
```

#### Get better results from scans

Use clean, upright, complete scans with readable text. Avoid extreme compression, glare, truncated pages and mixed orientations. Keep the original for comparison. The OCR image includes India-first language packs, but operators must check installed languages and deployment settings for their material.

OCR confidence is diagnostic metadata, not the probability that a bank account number or monetary value is correct. Manually verify identifiers, totals, dates, negatives, handwritten fields and multi-column reading order. For a financial process, route ambiguous extraction to a reviewer; never reconstruct unreadable digits from context.

#### Errors and maintenance

Corrupt, oversized, unsupported or zero-text documents fail explicitly. A failed upload is not an empty valid policy. If OCR fails, ask the operator to check Poppler/Tesseract/LibreOffice availability and language packs. If extraction works but search fails, investigate embeddings and indexing separately.

Assign a content owner, review date and replacement/deletion procedure. Record which agents use the knowledge set. Use approved retention and access policies for customer documents; deleting a document and deleting derived evidence/history are different operations.

Next: [First agent](/docs/first-agent), [Insurance assistance](/docs/bfsi-insurance), [Security and data](/docs/security-and-data).


### Connect business systems

URL: https://agenticorg.ai/docs/connectors
Audience: Administrators and integration owners. Reviewed: 2026-10-11.

#### Connector readiness is more than a green badge

A connector links the agent runtime to a business service. It needs the right tenant/company binding, credentials, provider permissions, tool implementation and operational health. A registered connector or successful health check does not prove that every advertised business action works.

![Illustrative connector catalog](/screenshots/connectors.webp)

This existing product screenshot illustrates the integration catalog, not live readiness in your tenant.

#### Prepare the connection

Name the integration owner and system-of-record owner. Obtain an approved sandbox or read-only account. List the exact data and actions needed. For BFSI, a core banking, LOS, claims or screening service requires the institution's approved API contract and access process; selecting a generic connector does not create that integration.

#### Register and bind

1. Open **Connectors**, find the provider in the native catalog, and select **Register**. Use the general **Register Connector** button only for a reviewed custom integration.
2. When native prefill is enabled, confirm the fixed provider name matches the registry entry. Otherwise enter the canonical registry name manually; a display label is not enough.
3. Enter the connector name, reviewed base URL, category, authentication type and rate limit.
4. Use the provider-specific protected credential fields or approved secret reference. Do not put secrets in prompts, screenshots or ordinary task inputs.
5. Review extra JSON configuration against the provider's contract. Do not assume arbitrary configuration creates a tool implementation.
6. Bind the connector to the correct company or documented tenant-wide scope.
7. Run the supported health/test action and inspect the safe result.

The native catalog's **Register** button can prefill the connector's exact registry name, category, endpoint and authentication type when the deployment enables the native-prefill rollout. Check the name before registering; a display label is not the registry ID. An unknown or outdated catalog link is refused rather than creating a generic connector. Without that rollout, the form remains the existing manual registration flow. For the four commonly requested providers, the reviewed credential keys are `access_token` and `phone_number_id` (WhatsApp), `account_sid` and `auth_token` (Twilio), `client_id`, `client_secret` and `refresh_token` (Gmail), and `client_id`, `client_secret` and `merchant_id` (Plural sandbox). A connector may also need provider-side permissions or additional settings. Do not paste real credentials into an issue or test report.

Registration stores credentials in the encrypted connector vault; it does not prove that the upstream account is authorized. A green connection probe proves only the operation it exercised. For external MCP tools, use the dedicated **Remote MCP** path below instead of registering a generic REST connector. Listing tools in another deployment is not evidence that this deployment has the same catalog or permissions.

Customers can bring credentials for their own provider accounts. WhatsApp needs a permitted business token and phone-number ID; Twilio needs an account SID and auth token; the guided Gmail form needs a customer OAuth client plus refresh token; Plural needs merchant-issued sandbox credentials before any live-rail review. The Gmail connection test now reads the authenticated user's profile without returning the mailbox address, and a successful profile check does not authorize sending mail. Register first, run the provider's bounded connection test, then separately prove each intended tool and scope with that customer's approved sandbox account. Leave the connector unverified if consent, scope, or provider access is missing.

The exact credential form differs by provider. Protected storage is not permission to grant unlimited upstream scopes. Prefer read-only scopes for the first pilot.

#### Connect a remote MCP server

The server must honor `Accept-Encoding: identity`; compressed responses are
refused to keep the response-size limit effective before decompression.

1. Obtain the server owner's approved public HTTPS **Streamable HTTP** endpoint and bearer token. Use the MCP endpoint itself, for example `https://tools.example.com/mcp`, not a website home page. OAuth consent flows, legacy HTTP+SSE endpoints and local stdio commands are not supported by this incoming connector path.
2. Open **Connectors > Remote MCP**. Enter a unique name such as `mcp_support`, the endpoint and token. Choose **Connect and discover tools**. AgenticOrg performs protocol initialization and paginated tool discovery before saving. A rejected token or incompatible server produces an error; it does not create a healthy connection.
3. Review the discovered descriptions and input schemas with the server owner. Server annotations are hints, not permission. All tools begin as write/unreviewed. Only tools advertised as read-only can be reviewed as reads, and obvious write names remain writes. A remote server can still misrepresent its behavior: register only trusted servers and use minimally scoped provider tokens.
4. Select the read-only tools you have reviewed and choose **Save read-only review**. Run one **Read-only connection probe** with non-sensitive arguments. A successful probe verifies that tool, not every server capability or any real speech/payment provider behind it.
5. In **Agents > Create Agent**, on the **Behavior** step of the Create Virtual Employee wizard, or in **Agent > Config > Edit**, select the remote connector and its exact tools. Save and reload the agent. Names are connector-qualified, such as `mcp_support__search`; a tool from another connection is not interchangeable.
6. Run a company-scoped agent with an appropriate delegated grant. The runtime rechecks persisted ownership, active connector, selected tools and current schema before dispatch. MCP registration and a read probe do not bypass agent grants, operator overrides or action policies.

```flow
Owner connects the HTTPS server | The endpoint and bearer token are saved only after protocol initialization succeeds.
Discover tools | Paginated discovery stores the encrypted token and the tenant's tool catalog.
Review read-only tools | The owner marks reviewed read tools; every other tool stays write/unreviewed.
Agent selects tools | The agent names the exact connector and the tools it may use.
Grant and action checks | Delegated grants, operator overrides and action policy apply.
Reload and compare the schema | Ownership, the active connector and the live schema are checked again before dispatch.
One bounded MCP call | The call runs once within the size and time caps below.
```

**Current boundary:** write/unreviewed tools may be selected but remain contained by the platform's action policy. This path does not enable arbitrary messaging, voice replies, payments or destructive actions. Grant labels remain conservatively write-scoped; the reviewed read classification is a separate execution-policy check. Tools and their output are untrusted source data, never instructions to expand permissions.

Use **Refresh** to rediscover a changed server or rotate its token. Unchanged read reviews are preserved; changed tools require another review. If a server changes between discovery and execution, the call is refused with a connection/schema error. Archive the connection to block subsequent calls across workers. A request already sent cannot be recalled by archiving.

Only public HTTPS destinations are permitted: no redirects, IP literals, internal hosts, URL-embedded credentials or query tokens. Requests have bounded durations, arguments, responses and discovery pages. Calls are not automatically retried, because a lost response does not prove an external action failed. Raw credentials are not sent to the model or returned in connector responses. Tenant/company credential bindings and personal connector ownership still apply.

These are input safety caps, not a count of available product integrations:

| Input or operation | Maximum |
| --- | --- |
| Discovered tools per connection | 100 |
| Discovery pages | 10 |
| Connector-qualified tool name | 64 characters |
| Object input schema | 32 KiB |
| Arguments | 64 KiB |
| Response | 1 MiB |
| Complete protocol operation | 30 seconds |

Local JSON pointer schema definitions are supported within bounded complexity. Recursive/dynamic
references, external references and regex-based schemas are refused explicitly.
Ask the server owner for a bounded compatible schema; do not remove network or
validation protections to make an incompatible server connect.

| Symptom | Next action |
| --- | --- |
| Connection rejected | Check endpoint transport, bearer token, server health and public network reachability |
| Tool not selectable or save rejected | Refresh the catalog and select the tool from the linked connector, not a copied name |
| Changed schema or unavailable tool | Refresh discovery, review permissions again and start a new run |
| Write / approval required | Use an approved governed action integration; a read-only review cannot authorize a write |
| Agent call refused but probe works | Check company binding, selected tools, agent lifecycle, grant and operator policy |

Keep real tokens and private server responses out of screenshots and support issues. Share the request ID, sanitized error and affected tool reference instead.

#### Grant the agent only what it needs

Open the agent configuration and select the appropriate connector and **Authorized Tools**. Verify that a permitted read call works for the selected company. Then verify that an ungranted tool and another company's resource are refused. Model access and connector access must be tested independently.

#### Validate the real contract

| Check | Evidence to collect |
| --- | --- |
| Authentication | A successful bounded provider request, without logging its secret |
| Scope | Required read/action allowed; forbidden action rejected |
| Mapping | Identifiers, dates, amounts, currencies and pagination are correct |
| Freshness | Timestamp/source state reaches the user-facing output |
| Failure | Rate limit, expired credential and unavailable provider are visible |
| Recovery | Safe retry/idempotency and an accountable escalation path |

Health freshness and credential presence are readiness signals, not an error-budget or sustained-sync guarantee. Run representative volume tests before relying on a connection operationally.

#### Maintain and troubleshoot

Rotate credentials through the approved secret path. Re-test after provider API, schema, scopes or tenant-binding changes. Monitor latency, failures and rate limits. Disable dependent schedules when the source contract changes.

If company A works and company B does not, inspect binding before changing the code or copying IDs. If a custom URL is rejected by network policy, have security approve the legitimate endpoint; do not turn off SSRF or private-network protections.

Next: [Workflows](/docs/workflows), [Model setup](/docs/model-setup), [BFSI reconciliation](/docs/bfsi-reconciliation).


### Build and run workflows

URL: https://agenticorg.ai/docs/workflows
Audience: Process owners. Reviewed: 2026-10-11.

#### Turn a process into explicit steps

A workflow coordinates agent tasks, conditions, waiting, notifications and human review. Start with a process map and a system-of-record owner. Decide what happens when inputs are missing, a provider fails or a person rejects the proposed action.

![Illustrative workflow workspace](/screenshots/workflows.webp)

The screenshot illustrates the existing workflow view. Your available definitions and execution state depend on workspace configuration.

#### Create a definition

Open **Workflows > Create Workflow**. Choose **Describe in English** to generate a draft from a description of the business process, or **Use Template** to enter or edit a reviewed definition. The definition form includes name, version, domain, trigger type, optional cron schedule and JSON steps. Generated output is not an approved operational process.

A third tab, **Build visually**, appears only where the deployment turns on the visual builder (`AGENTICORG_WORKFLOW_BUILDER_V2_ENABLED`, off by default). It draws agent steps, human checkpoints, conditions and failure paths, lists every validation problem, and copies valid steps into the definition form. With the setting on, saving a definition that cannot be drawn and run is refused with each problem named.

The available step options include agent, condition, human-in-loop, parallel, wait, wait-for-event, notify, transform and collaboration. Review each option against the runtime implementation and selected integration. Do not infer that selecting a step type provisions its external system.

1. Give the workflow a task-specific name and version.
2. Choose the domain and start with a manual trigger.
3. Select authorized agents and define structured inputs.
4. Add a condition for missing/invalid evidence.
5. Add human review before a consequential action.
6. Define success and failure routing, bounded retries and a time limit.
7. Validate the JSON steps; where **Build visually** is available, check the drawn paths and its validation list.
8. Save and run with synthetic inputs before scheduling.

#### Worked process: complaint response preparation

```flow
Intake | Accept the complaint reference in the authorized company.
Triage | Classify the request and retrieve the current procedure.
Evidence check | Route missing or conflicting information to a reviewer.
Human review | Approve a response draft, not an unverified account action.
Handoff | Send only through an explicitly configured and authorized integration.
```

If no email or CRM action has been implemented and approved, stop at the prepared output. Do not rename it "sent". Workflow notification and business action permissions are independent.

#### Run and inspect history

Open the definition/detail page, supply the expected payload and start a run. Inspect the workflow run screen for each step's status, output, errors and waiting conditions. A waiting approval is not a hung workflow. A failed provider step should not be presented as successful completion.

Test condition branches and review rejection as deliberately as the happy path. Use a missing document, unavailable connector, duplicate event and rejected approval. Check that no unauthorized next step runs after a refusal.

#### Schedules and recovery

Only schedule a workflow when the operator has confirmed worker/scheduler availability, timezone, frequency, permissions, retries and duplicate handling. A saved cron string is not proof that a background worker is deployed. Begin with a low-frequency schedule and inspect actual runs.

Before rerunning, inspect whether any external step already completed. Resume at the documented safe step rather than replaying a money-moving or communication action blindly. Pause schedules during provider outages, schema changes and credential rotation where needed.

Next: [Approvals](/docs/approvals), [Audit and monitoring](/docs/audit-and-monitoring), [Evaluation](/docs/evaluate-and-rollout).


### Voice, speech-to-text and text-to-speech

URL: https://agenticorg.ai/docs/voice
Audience: Voice administrators. Reviewed: 2026-10-11.

#### Shipped voice path

The implemented voice runtime is a signed Twilio webhook loop using provider-managed speech recognition and text-to-speech. It uses the agent's instructions, tools and tenant boundaries. Selecting another voice/STT/TTS option in configuration does not prove that its runtime worker is shipped or ready.

The administrator accesses **Voice Agents / Voice Setup**. You need a Twilio account, approved number, credentials, active mapped agent, reachable callback URLs and a budget owner. Phone calls may incur charges.

#### Configure and validate

1. Select the target agent and Twilio provider.
2. Enter the account SID, auth token and provider number through the protected form.
3. Test provider credentials.
4. Select **Provider speech recognition** and **Provider text-to-speech**.
5. Choose the call language and save.
6. Configure the displayed inbound/status callback URLs in the provider console where provisioning is not automated.
7. Check runtime health for the exact agent, not merely credential storage.

```flow
Caller speaks | Twilio collects a speech turn for the configured number.
Signed callback | AgenticOrg verifies the signature and tenant/agent binding.
Bounded agent turn | Approved model/tools prepare a safe text response.
Spoken reply | Escaped TwiML returns speech and the next input prompt.
Call evidence | Status and encrypted bounded text are recorded; history is masked.
```

#### Run a safe end-to-end test

Agree a test phone destination and time window with the owner. Use a synthetic script: ask a supported question, stay silent, ask an ambiguous question and ask for a prohibited account/payment action. Verify recognition, spoken reply, escalation wording, actual provider call status and masked call history.

Never place a paid outbound call to an unapproved number. A local signed-webhook simulation tests software behavior but not the PSTN connection, acoustic quality or provider routing. Both forms of evidence have different purposes.

#### Privacy and service boundaries

AgenticOrg does not store call audio in this path or expose full transcripts in the call-history API. Bounded conversation text is encrypted. The separate **Calls** screen (speech intelligence, off by default) keeps uploaded recordings and their transcripts encrypted; see [Calls](/docs/review-and-operations-screens#calls-recordings-transcripts-and-summaries). The provider's recording, retention and regional settings are separate and must be reviewed with your data owner.

For BFSI, general policy answers and complaint-routing assistance are appropriate starting points. Voice identity, balance disclosure, account access, transfer instructions and card actions need institution-approved authentication and integrations. A caller saying an account number is not identity verification.

#### Troubleshoot

No callback: verify provider URLs and routing. Signature rejection: inspect canonical URL/signing configuration; do not disable validation. Provider-ready but no answer: test model/agent activity and tool permissions. Bad transcription: inspect language, microphone/network and a representative test set. Business failure: return a safe spoken error, never claim the action succeeded.

Next: [BFSI customer service](/docs/bfsi-customer-service), [Troubleshooting](/docs/troubleshooting).


### Browser RPA and schedules

URL: https://agenticorg.ai/docs/rpa
Audience: Automation administrators. Reviewed: 2026-10-02.

#### When to use browser automation

Use RPA for a reviewed task on an authorized web-only system when a supported API is not suitable. Prefer an API for stable structured integration. RPA is an explicit external action, not a way around permissions, website policy, MFA or CAPTCHA.

The administrator screens are **RPA Scripts** and **RPA Schedules**. Available scripts come from the configured catalog. A visible script is not permission to run it against a real customer system.

#### Prepare a reviewed script

Document target system/domain, intended action, business owner, required inputs, credentials, success signal and recovery procedure. Approve the destination through normal egress policy. Private/loopback/metadata destinations and unsafe DNS behavior are guarded; do not disable those controls to complete a test.

#### Run one bounded task

1. Select the reviewed script in **RPA Scripts**.
2. Inspect its expected inputs and whether it reads or changes data.
3. Use approved test credentials and synthetic records first.
4. Run explicitly and wait for the structured result.
5. Inspect durable history, duration, timeout/failure state and supported screenshots/evidence references.
6. Confirm the business outcome in the target system.

```flow
Operator selects task | The script and inputs describe an intended authorized action.
Egress and input checks | Tenant permissions and destination policy are enforced.
Browser execution | Playwright performs the bounded script with a timeout.
Result and history | Success, refusal or failure is recorded with supported evidence.
Business verification | Confirm the authoritative target record before retrying or expanding.
```

Browser navigation success does not prove a submission or account change completed. A screenshot can show what was visible, but a durable target reference/status is stronger evidence for a business action.

#### Schedule only after reproducible tests

Confirm a worker/browser runtime is installed, reviewed schedule frequency and timezone, concurrency, credential handling and retry policy. A saved schedule is not proof that a runner is deployed. Verify real scheduled executions and an operator-owned alert path.

Test a selector change, expired session, missing field, blocked destination, timeout and duplicate request. Keep screenshots and logs free of unnecessary customer data and secrets. Use protected credential custody, not source-code constants.

#### Recover safely

When a site changes, pause dependent schedules and inspect the changed contract. Do not blindly replay a possibly completed submit. Verify whether the target system already changed and use its documented recovery/idempotency path. A CAPTCHA or MFA step should move to an authorized human process, not an evasion mechanism.

For BFSI, first use a read-only internal/test portal task with approved network and data access. A core banking or payments portal is not an appropriate target merely because it is reachable from a browser.

Next: [Connectors](/docs/connectors), [Security and data](/docs/security-and-data), [Evaluation](/docs/evaluate-and-rollout).


### Industry packs and business dashboards

URL: https://agenticorg.ai/docs/industry-packs
Audience: Department leads. Reviewed: 2026-10-11.

#### Packs are starting points, not automatic integrations

An industry pack can supply available agent definitions, prompts or workflow starting points for a domain. Inspect exactly what the selected pack installs. Its presence does not provision external accounts, certify a workflow or guarantee a business outcome.

The **Industry Packs** screen is administrator-oriented. Department users work through permitted agents, workflows and role-specific dashboards after configuration.

#### Use a pack responsibly

1. Choose a pack aligned with a real process and accountable owner.
2. Inspect the agents, tools, prompts, dependencies and intended outputs.
3. Review installed/created candidates in the correct company context.
4. Configure model credentials and required business connectors separately.
5. Replace example procedures with approved, current content.
6. Test with synthetic data and explicit refusal scenarios.
7. Promote only the tested components needed for your pilot.

If a pack or template names an unconfigured provider, it is not ready to run. A template's confidence setting is not measured accuracy.

#### Department workspaces

| Workspace | Typical work | Human boundary |
| --- | --- | --- |
| Finance/CFO | AP/AR, reconciliation, treasury, expenses, close and analysis | Posting, release and financial sign-off require the configured authority |
| HR/CHRO | Onboarding, recruiting, learning, payroll preparation | Employment and payroll decisions remain authorized human processes |
| Marketing/CMO | Research, content, campaigns and CRM follow-up | Publishing, spend and customer communication need explicit permissions |
| Operations/COO | Support, contracts, vendors and IT exceptions | System changes and contractual actions need review |
| Partner/company workspaces | Multi-company operations and client context | Company selection never bypasses tenant isolation |

Dashboard visibility is role-based. A missing menu can be expected permission behavior. Metrics describe the screen's data and reporting window; do not treat every summary as a full-day live total.

#### BFSI configuration examples

The **Banking Pack** offers agent templates for retail and SME banking operations: loan underwriting support, KYC review, collections, complaint handling and bank reconciliation. Each template sends defined cases to a person through its review condition and carries a confidence floor. Installing it creates the agents in shadow and its two workflows with manual triggers; it does not schedule work, promote an agent to active or connect a bank system. Some packs on the screen, such as Insurance and Legal, are listed but cannot be installed yet.

Bank onboarding can use governed cases with reviewed evidence providers and decision authority. Insurance assistance can use a custom document-review agent plus OCR and workflow approvals. Reconciliation can use finance definitions with a bank's approved ledger/export interface. These are explained in the [BFSI playbooks](/docs/bfsi-business-onboarding), not presented as universally installed bank products.

#### Maintain the business layer

Assign prompt and policy owners, an approval backup, connector operations and a training owner. Review pack changes before updating deployed candidates. Measure task quality against human-reviewed cases rather than counting how many agents were installed.

Next: [Create agents](/docs/create-agents), [Adoption checklist](/docs/adoption-checklist).


### Approvals and human review

URL: https://agenticorg.ai/docs/approvals
Audience: Reviewers and approvers. Reviewed: 2026-10-11.

#### What human review should answer

Review means understanding the evidence, authority, proposed action and possible effect. It is not clicking approve because an agent has a high confidence score. Assign the reviewer before enabling a workflow; an unowned queue creates operational delay.

Open **Approvals** with an authorized role. The standard queue supports reviewing agent/workflow escalations. Governed business cases use a separate case queue and decision-grant process described in [Governed cases](/docs/governed-cases).

#### Review a standard escalation

1. Confirm the company, run/agent reference and requested action.
2. Read source evidence and any missing/conflicting information.
3. Check the policy/HITL reason and connector/tool scope.
4. Verify whether the action is a draft, an external change or a business decision.
5. Approve or reject through the supported control only within your authority.
6. Inspect the recorded result and downstream status. Approval does not prove that the provider action completed.

A failed queue load must not be interpreted as "no pending approvals". Resolve an error and refresh the authoritative state before making a decision.

#### Standard approval versus governed-case decision

| Path | What it reviews | Who supplies decision authority |
| --- | --- | --- |
| Agent/workflow HITL | A run's proposed task or escalation | Authorized workflow/business reviewer under the configured rules |
| Governed-case screening review | Accept/override a screening proposal with evidence | Authenticated human analyst; an override requires a reason |
| Governed-case final decision | Exact current case version and semantic action | External decision-grant issuer and named approvers |

Do not use a generic approval button as a substitute for a governed-case decision. The case console cannot mint decision authority. Machine credentials cannot sign in as a human reviewer.

#### Handling changed or incomplete evidence

If a source changes while you review, inspect the current version again. A governed-case decision request can expire, be superseded or be refused because the case changed; create a new request for the current memo instead of reusing old approval evidence.

Request missing information or reject an unsafe proposal. Do not ask the agent to fill gaps with assumptions. A refusal is a useful safety outcome when authorization or evidence is absent.

#### Multi-person approval rules

When an approval policy applies to an item, the person who requested it cannot decide it (`403`). Each person votes once per item across every step: a second vote returns `409`, so a policy that needs the same person at two steps cannot complete. A step whose condition cannot be evaluated for the item, for example because the item lacks a field the condition names, still applies and needs its own approvers. If the item's policy is deleted, replaced, or loses the step the item is waiting on, decisions return `409` and the item stays pending until it expires.

Where the platform operator sets the stricter condition mode (authority flag `approvals.unevaluable_condition.deny`, off by default), an approval on an item with such a step returns `409` `approval_decision_refused` with reason code `approval_condition_unevaluable` and is not counted; a rejection is still accepted. These refusals are the policy working. Ask the policy owner to correct the policy or assign another reviewer; do not sign in twice as different identities.

#### Operating the queue

Assign primary and backup reviewers, a review target, an escalation contact and absence coverage. Track queue age and rejection reasons. Separate preparation from approval wherever your policy requires it. Reviewers need training in the task domain, not only product navigation.

For BFSI, loan, onboarding, claim, sanction, account-change and payment decisions remain with the institution's authorized process. Product functionality is not regulatory approval or certification.


### Governed business onboarding cases

URL: https://agenticorg.ai/docs/governed-cases
Audience: BFSI analysts and authorized approvers. Reviewed: 2026-10-11.

#### What a governed case is

A governed business case brings read-only investigation, cited evidence, deterministic policy results, screening proposals and human decision authority into one traceable record. An agent may investigate and prepare a recommendation. It cannot approve, decline, close, file or pay through this case path.

This feature is tenant-gated and configuration-dependent. Your operator must configure the active case-role agents, reviewed provider manifest, reviewed policy, Grantex grants and decision issuer. Shipped example policies are not production-approved bank policies.

#### Where to work

The case queue is at `/dashboard/approvals/cases`. Open a case at `/dashboard/approvals/cases/{case_ref}`. These screens require the relevant scopes and tenant feature flag. `governed_cases_disabled` means the feature is not enabled; it is not an empty successful queue.

```flow
Application submitted | A reviewed API/workflow supplies the authorized business application.
Read-only investigation | Registered tools check permitted evidence under grants and exact purpose controls.
Memo and policy | Findings carry citations, missing items, risk tier and fired rules.
Analyst review | A person reviews screening proposals and requests missing information.
Human decision | Named approvers use the configured issuer; AgenticOrg records verified grants.
Signed handoff | The operator's system receives the current case outcome; it owns the business action.
```

#### Read the case correctly

Inspect each memo section: complete, partial, not available and provider error mean different things. Missing evidence is not a clean result. Citations identify the provider, upstream record, field and retrieval time. Where retained, **Show the passage** retrieves encrypted, digest-checked evidence as text.

The policy section shows the policy ID/version, score, tier, input digest and fired rules. Model confidence is metadata and gates nothing in this case path. A recommendation marked `requires_human_decision` is a proposal, not approval.

#### Review screening proposals

Compare identifiers and evidence. **Accept** preserves the proposed outcome; **Override** requires a different outcome and a written reason. The server records the signed-in human identity. A review is written once and only while the case is awaiting decision. It does not close the upstream screening hit automatically.

#### Request and record the final decision

1. Choose the outcome to request. Supply a reason if it differs from the recommendation.
2. Open the issuer's approval page. The person authenticates and performs required step-up there.
3. Watch approval progress, including a distinct second approver when required.
4. Record the decision only when valid grants exist for the current exact case version/action.

If the issuer is unconfigured, the default verifier refuses decisions. `decision_required`, `same_approver`, `case_changed` and `decision_service_not_configured` are meaningful reasons, not errors to hide.

#### Integrate with the institution

Applications and signed case handoffs require reviewed API integration. The console is not a universal application-intake form or core-banking adapter. The signed outbox and REST case record provide evidence to your system of record; the institution controls account opening, monitoring, reporting and retention.

Provider events reach a tenant-specific address. A tenant administrator signed in as a person reads it from `GET /api/v1/case-push/provider-webhook-inbox?provider=<name>` and gives it to the provider; treat it as a credential. It has the form `/api/v1/webhooks/providers/{tenant_id}/{provider}/{token}`; the earlier tokenless path answers 404. A delivery to that address within the 256 KiB body cap is answered with `202` while governed cases are on for the tenant (a larger body gets `413`), and one that cannot be verified is recorded without being acted on. Rotating `AGENTICORG_SECRET_KEY` changes every tenant's address, so re-point the providers after a rotation.

Deciding, withdrawing, requesting a decision, reviewing a screening disposition and approving an information request need a person's session. An API key or agent token gets `403` `human_session_required`.

AgenticOrg pins the Grantex Python SDK (`grantex==0.7.1`) and calls its enforcement check with the grant token, connector, tool and any numeric amount. It does not pass a case id or case purpose, so a token's case purpose and per-case caps are not checked on this path. The role's case-purpose allowlist is a local AgenticOrg control, and pooled grants are not bound to one case. Evaluate that boundary explicitly before enabling a production process.

Next: [BFSI onboarding walkthrough](/docs/bfsi-business-onboarding), [Security and data](/docs/security-and-data).


### Documents, conversations, calls and workbenches

URL: https://agenticorg.ai/docs/review-and-operations-screens
Audience: Administrators, reviewers and operations leads. Reviewed: 2026-10-11.

#### Six screens that ship switched off

Six console screens belong to services that are built into the product but switched off in a default installation. Each needs its own deployment setting, which a platform operator turns on. While a service is off, it processes nothing and its other routes answer as not found.

| Screen | Sidebar entry and who sees it | Deployment setting (off by default) | While it is off |
| --- | --- | --- | --- |
| Documents | Always listed for roles that can open the approval queue | `AGENTICORG_IDP_ENABLED` | The page shows "Document processing is off for this deployment"; the API answers `404` `idp_disabled` |
| Conversations | Always listed for administrators | `AGENTICORG_CONVERSATION_V2_ENABLED` | The page shows "Conversational services are off for this deployment"; the API answers `404` `conversation_disabled` |
| Workbenches | Always listed for every role except merchant | `AGENTICORG_WORKBENCH_V2_ENABLED` | The page says "Workbenches are off for this deployment." |
| Calls | Administrator, COO and auditor; hidden until the service is on | `AGENTICORG_SPEECH_INTELLIGENCE_ENABLED` | No sidebar entry |
| Transactions | Administrator, CFO, COO and auditor; hidden until the service is on | `AGENTICORG_TRANSACTION_INTELLIGENCE_ENABLED` | No sidebar entry |
| Lineage | Administrator, CxO roles, auditor and domain lead; hidden until the service is on | `AGENTICORG_LINEAGE_ENABLED` | No sidebar entry |

An "off for this deployment" message is configuration, not an empty queue. Ask the platform owner whether the service is meant to be on; do not treat it as "nothing to review". The sidebar only offers a page; the server still checks each request against your role and scopes.

```flow
Choose one service | Pick the screen a pilot needs and name its business owner and reviewer.
Agree the data terms | Confirm what the service keeps, who may read it and how it is removed.
Turn on the setting | The platform operator sets the service's deployment setting.
Confirm the screen | Reopen the screen and check that the off message has gone.
Test with fictional material | Run one synthetic document, call or record through the service.
Review before relying on it | A named person checks each output before anyone acts on it.
```

#### Documents: review extracted fields

With document processing on, a file sent to `POST /api/v1/idp/analyse?store=true` is split into typed documents (bank statement, salary slip, invoice, identity document and other types in the catalogue), and its fields and tables are extracted with the place on the page each came from. The screen has no upload button; files arrive through that API.

Filter the list by **Needs review**, **Processed**, **Approved**, **Rejected** or **All**. Open a file to see each page with a box drawn around every field. The box colour shows whether a field was read with high or low confidence, is missing, or has been corrected. Click a field to jump to its page, type a correction and choose **Save**; the extracted value stays visible beside your correction. Then **Approve** or **Reject** the whole file. The review reasons at the top say why a file was routed to a person, for example a missing required field or a page whose text could not be read.

A confidence colour is a hint, not a verified value. Check account numbers, amounts, dates and identity numbers against the page image every time.

#### Conversations: watch and take over a chat

With conversational services on, an administrator sees every chat conversation in progress or escalated, newest activity first, with who holds each one. Open one to read its transcript. **Take over** stops the runtime from answering: the user's next messages are shown to you and your replies reach the user's chat. **Release** hands the conversation back to the runtime. The screen updates through the live feed, which carries only the fact that something changed, never the message text.

The same setting turns on banking intents in chat and passes earlier turns to the agent as context; see [Run agents and use chat](/docs/run-and-chat).

#### Workbenches: one place per role

With workbenches on, the index lists the workbenches your role holds or an administrator assigned to you. A workbench shows tabs with the number of items waiting behind each. Most tabs open the page they name (for example Documents or Approvals), and that page applies its own permissions. A content-drafts tab lists drafts waiting for a decision with **Approve** and **Reject**. Use **Refresh counts** before reporting a queue size; a dash means the count is not available, not zero.

#### Calls: recordings, transcripts and summaries

With speech intelligence on, a recording sent to `POST /api/v1/speech/recordings` is split by speaker and transcribed, by a local engine where the deployment installed one or through the tenant's own speech-provider credential. The audio and the transcript are kept encrypted under the tenant's key. The screen has no upload button.

Open a recording to see each speaker's talk time and turns. **Summarise** asks a model for the intent, key points and next actions; **From the words only** builds the same summary from the transcript without a model. **Redact spoken data** finds spoken card numbers, one-time codes, CVVs and PINs, replaces them in the transcript, silences them in the audio and records only the kinds and times removed. Sentiment, empathy, talk ratio and escalation risk are review aids for a supervisor, not a judgement of the staff member or the customer. Agree retention and removal of recordings with the data owner before turning the service on; see [Security and data](/docs/security-and-data).

#### Transactions: findings under human disposition

With transaction intelligence on, transaction records are loaded through the API and detectors look for patterns such as structuring and pass-through movements. Each finding names an entity, a summary, a severity and its supporting records. Filter by **Open**, **Confirmed**, **Escalated** or **Dismissed**.

**Draft narrative** writes a draft account of the finding, by a model or from the facts alone, with what is still to check. **Download evidence** exports the finding with its supporting rows and a digest over the package. **Show the fund flow** draws the accounts and counterparties around the entity across a chosen number of hops. A reviewer with approval access records **Confirm**, **Escalate** or **Dismiss**; a dismissal needs notes. A narrative is a draft for an investigator, never a regulatory filing, and auditors can read findings without deciding them.

#### Lineage: where a kept item came from

With lineage on, ingestion records each kept item's source, version and processing steps. Search by kind and reference, choose **Upstream (sources)**, **Downstream (uses)** or **Both** and a number of hops, then open an item to trace it. The sync-sources table lists scheduled sources with their last run, and **Run now** starts one. Items ingested while lineage was off have no recorded chain, so "No provenance kept yet" can mean the item predates the switch.

Next: [Approvals](/docs/approvals), [Security and data](/docs/security-and-data), [Troubleshooting](/docs/troubleshooting), [Self-hosting](/docs/self-hosting).


### Audit, monitoring and run history

URL: https://agenticorg.ai/docs/audit-and-monitoring
Audience: Operators and auditors. Reviewed: 2026-10-11.

#### What evidence you should inspect

Run evidence helps answer who requested a task, which company/agent handled it, which tools were attempted, what failed, what required review and what outcome was reported. Use **Audit Log**, **Observability**, agent history and workflow run detail according to your role. The separate administrator [run timeline and workload view](/docs/run-observability) is opt-in and has a bounded time window; it is not an exhaustive audit stream.

![Illustrative audit workspace](/screenshots/audit.webp)

This screenshot illustrates an existing product view. It is not evidence of your tenant's current activity or a measured delivery guarantee.

#### Investigate a task end to end

1. Find the run/case reference and timestamp.
2. Confirm the tenant/company context and initiating identity.
3. Inspect the agent and prompt/model version where recorded.
4. Read tool outcomes and safe failure/refusal reasons.
5. Verify citations, provider timestamps and missing evidence.
6. Inspect approval or case-decision authority separately.
7. Check the system-of-record outcome for any external action.

Do not infer that an absent event means no action occurred. Confirm the view's scope and whether the event writer for that path is implemented.

#### Understand screen limits

Dashboard Recent Activity and Observatory read audit history. Observatory polls the newest 20 rows every five seconds and labels that scope. This is not an exhaustive live stream or a full-day activity total. An internal resilient feed exists in the repository. Its only writer is the conversation supervisor console (off by default behind `AGENTICORG_CONVERSATION_V2_ENABLED`), which announces conversation changes, never message text, for the Conversations screen; no other operational event is published to it, so do not represent it as universal real-time monitoring.

In a tenant that keeps spend rate cards, commitments, invoices, reconciliations or spend jobs, the Audit Log hides those audit rows from every reader who is not a human administrator or auditor, including domain roles and machine credentials, even after spend intelligence is turned off. This is `AGENTICORG_SPEND_AUDIT_COMMERCIAL_FILTER`, on by default; `false` shows them to every reader as before. Where the deployment turns on the tamper-evident audit chain (`AGENTICORG_AUDIT_CHAIN_ENABLED`, off by default), audit rows are linked into a hash chain, and a reader with audit access can read the chain status and verify the links through `GET /api/v1/audit/chain` and `GET /api/v1/audit/chain/verify`.

For governed cases, inspect transitions, memo citations, policy inputs/version, analyst reviews, decision-grant evidence and signed handoff delivery history. The case record can retain stronger lineage than a general activity summary.

#### Establish operational measures

Choose metrics tied to your task: successful and refused runs, correct answers, missing-source rate, approval age, connector error/latency, OCR review rate, workflow retries and actual downstream outcomes. Record the time window, sample size and workload. Do not turn a sample result into a platform-wide accuracy claim.

#### Incident workflow

Stop the affected external-action schedule or agent path through supported controls. Preserve safe references, isolate the provider/configuration issue, and ask the accountable operator to investigate. Never paste secrets or full customer records into ordinary issue reports.

Check [Service Status](https://agenticorg.ai/status) and your own deployment health separately. A public service status page cannot certify the health of every tenant connector or self-hosted bank environment.

Next: [Run observability](/docs/run-observability), [Guardrails](/docs/guardrails), [Troubleshooting](/docs/troubleshooting), [Security and data](/docs/security-and-data), [Evaluation](/docs/evaluate-and-rollout).


### Guardrail rules, dry runs and enforcement

URL: https://agenticorg.ai/docs/guardrails
Audience: Tenant administrators and security owners. Reviewed: 2026-10-11.

#### Configure and test guardrails

Tenant-scoped rules evaluate text at the input, retrieved-evidence, model-output and tool-action stages. A rule names a detector, threshold, optional agent/use-case/risk-tier scope, priority and response. Detector identifiers are `sensitive_data`, `toxicity`, `pattern`, `injection`, `output_policy` and `grounding`. Action values are `flag`, `mask`, `redact`, `tokenise` and `block`; API validation enforces detector/action compatibility.

Tenant administrators manage rules on the [Guardrails](https://app.agenticorg.ai/dashboard/settings/guardrails) page. It shows the mode in effect (hooks off, flag-only or enforcing), lists the rules with what each applies to, adds, changes, enables, disables and deletes a rule, and dry-runs a stage over a text. Detector options are edited as JSON, starting from an example for the chosen detector. The page changes rules only; hooks and tenant enforcement are switched on through their own approved controls.

The same operations are available under `/api/v1/guardrails` to an approved client acting as a tenant administrator and holding `governance.guardrails.sensitive.read` or `.write`: `GET /status`, `GET/POST /rules`, `PATCH/DELETE /rules/{rule_id}`, `POST /evaluate`, `GET /adversarial` and `POST /adversarial/run`. Do not copy a privileged key into a browser console or commit it to a script.

```flow
Check effective status | Open the Guardrails page and read the banner: hooks off, flag-only or enforcing.
Create a narrow rule | Choose one stage, detector, threshold, response and explicit scope.
Dry-run examples | Use the dry run with synthetic allowed and flagged text; inspect the outcomes and the text after the rules.
Review detector limits | Check false positives, missed cases, latency and failure behavior with the domain owner.
Enable only through approved controls | Confirm hooks and tenant enforcement configuration before relying on blocking or transforms.
Monitor and revise | Correlate rule outcomes with run evidence; keep a rollback owner and test after edits.
```

#### Understand the modes

Rules can be stored while platform hooks or enforcement are off. Hooks are disabled by default. With hooks enabled but tenant enforcement off, evaluations are flag-only: the request continues unchanged while findings are recorded for observation. The `/evaluate` endpoint is a dry run: it returns the result the rules would produce, including transformed text or `allowed: false`, but does not enforce that result on a live call and does not write an audit outcome. A dry run is therefore not evidence that production traffic is protected.

Enforcement is a separate setting. When active, a matching transform changes the text before it continues, and a blocking rule refuses that stage. A strict runtime may refuse a stage if it cannot safely load rules or a detector fails; behavior depends on the deployed strictness configuration. Confirm the effective status, hook configuration and runtime logs with your platform owner rather than inferring enforcement from the existence of a rule.

#### Scope and detector behavior

Rules match one of four stages: `input`, `retrieval`, `output` or `action`. Optional `agent_id`, `use_case` and `risk_tier` fields narrow a rule. Without those fields, the rule can apply to every call at that stage. Rules run in priority order, and a block takes precedence over a transform. Pattern rules are bounded and reject known unsafe regular-expression shapes; keep patterns short, specific and reviewed.

Sensitive-data recognition includes configured patterns for common identifiers such as payment cards, Aadhaar, PAN, GSTIN, email, UPI and phone. Recognition quality depends on the active analyzer and fallback recognizers. Toxicity and prompt-injection detection are signals, not proof of intent or a complete security boundary. A `grounding` rule (output stage; flag or block) compares each sentence of an answer with what the run retrieved and reports claims, and figures, that the retrieved text does not carry. It is a word-level check, not a judgement of meaning: it catches answers written without the retrieved material, and it can flag a faithful paraphrase. In the dry run, paste the retrieved text as the context. Test representative languages, formats, OCR noise and adversarial inputs. Retain a human review path for high-impact decisions.

#### Operational checklist

- Start in flag-only mode with synthetic cases and inspect false positives and misses.
- Run the adversarial set on the Guardrails page against your rules. It reports, per category, the synthetic attacks your rules detect, the ones they miss and the benign texts they wrongly catch. Some attacks are included because pattern-based detectors miss them, so a score below 100% is expected; the result describes that corpus only.
- Verify exact tenant, agent, use-case and risk-tier matching, including missing-context behavior.
- Test each action separately; ensure masks/redactions do not destroy required business context.
- Verify that blocked input, retrieval, output and tool-action cases stop at the intended boundary.
- Confirm audit permissions, correlation IDs, retention and incident ownership.
- Keep a rollback rule/configuration and rerun regression cases after every detector or policy change.

Guardrails do not replace access control, data minimization, provider contracts, connector permissions, human approvals or institution policy. They are one control in a layered system.

Next: [Model Gateway](/docs/model-gateway), [Security and data](/docs/security-and-data), [Audit and monitoring](/docs/audit-and-monitoring), [Troubleshooting](/docs/troubleshooting).


### Run timelines and workload observability

URL: https://agenticorg.ai/docs/run-observability
Audience: Administrators and operators. Reviewed: 2026-10-11.

#### Inspect run timelines and workload

The administrator-only **Observability** screen (`/dashboard/observability`) has Traces, which lists recent instrumented runs and a span waterfall for one run, and Workload, which summarizes review deadlines and selected tenant outcomes. Traces and Workload are read-only views. Where the deployment turns on synthetic checks (`AGENTICORG_SYNTHETIC_CHECKS_ENABLED`, off by default), a third **Checks** tab lists the tenant's scheduled probes with their latest results and lets an administrator add or run one. Where the debugging console is on (`AGENTICORG_RUNTIME_DEBUG_CONSOLE_ENABLED`, off by default), a run recorded while it was on offers **Step through** to read its checkpoints one step at a time. They help an operator investigate; they do not replace the audit log, provider billing, a system-of-record check or an incident process.

```flow
Open Observability | Sign in as an authorized administrator and select the intended company.
Check recording state | Read the tracing/timeline status before interpreting an empty run list.
Find a run | Filter recent runs by agent, then open one run to inspect parent/child spans and events.
Compare workload | Review pending/overdue reviews and the one-hour run, model-call and guardrail summaries.
Follow the correlation | Use run/correlation identifiers to inspect audit details and the downstream system separately.
```

#### Traces and timelines

The list requests up to 50 recent stored runs and can filter by agent ID. A run detail displays its stored spans in relative time order, including duration, parent relationship, status and available attributes/events such as model decisions, tool outcomes, guardrail outcomes and exceptions. Data is limited to what that deployment records; missing spans do not prove that no work occurred.

Before a platform owner changes `AGENTICORG_TRACING_ENABLED` or `AGENTICORG_TRACING_TIMELINE_ENABLED`, agree on an approved OTLP endpoint and protocol, sampling, data classification, storage and retention. Both controls default to off; strict production-like environments require a valid exporter endpoint when tracing is enabled. Confirm the effective retention setting with the platform owner before relying on historical timelines. Never send sensitive payloads to an unapproved telemetry collector.

#### Workload view

Workload refreshes about every 15 seconds. Its run, model-call and guardrail summaries cover the most recent hour. Review counts and deadlines come from the tenant's pending human-review queue. Each panel can report unavailable data independently; a dash or an error means unknown/unavailable, not zero. Model-call summaries depend on model-gateway record capture, and guardrail block/transform counts depend on persisted guardrail audit outcomes.

Use the panel's stated time window and generated time when comparing it with another report. This is not a durable event stream, full audit export, cross-tenant dashboard or service-level guarantee. Do not use it as the sole evidence for a financial, compliance or customer-impact decision.

#### A practical investigation

1. Capture the run ID, correlation ID, company, agent and approximate time.
2. Check whether tracing and timeline storage were enabled during that interval.
3. Follow span status, duration and error events; identify the earliest failing dependency.
4. Compare guardrail and model-gateway decisions with the audit view.
5. Confirm any external action with its authoritative system (for example, the provider or connected business application).
6. Record the safe error code, deployed commit and remediation owner; do not attach credentials or full customer payloads.

If the view is empty, first verify permissions, selected company, feature configuration, retention window and whether the run path emits timeline spans. See [Audit and monitoring](/docs/audit-and-monitoring), [Model Gateway](/docs/model-gateway), [Guardrails](/docs/guardrails) and [Security and data](/docs/security-and-data).


### Evaluate and roll out safely

URL: https://agenticorg.ai/docs/evaluate-and-rollout
Audience: Product owners and administrators. Reviewed: 2026-10-11.

#### Define success before running tests

Choose the task, owner, expected output, permitted tools, prohibited actions and escalation behavior. Use representative examples, not only a single easy prompt. A confidence percentage, template name or passed unit test does not establish business accuracy.

#### Build a small reviewed test set

Include normal inputs, incomplete files, conflicting procedures, stale evidence, incorrect company references, provider failures and attempts to request forbidden actions. For OCR, include realistic scans; for voice, include accent/noise and silence; for RPA, include expired sessions and changed selectors.

| Dimension | Example acceptance question |
| --- | --- |
| Grounding | Is each material fact supported by an authorized source? |
| Correctness | Does the result match the reviewed answer? |
| Permissions | Are cross-company and ungranted requests refused? |
| Human control | Does consequential work stop at the intended review boundary? |
| Recovery | Are retries bounded and duplicate effects prevented? |
| Usability | Can a second operator reproduce the task without the builder? |
| Operations | Are latency, cost, volume and failure handling acceptable for this workload? |

#### Run candidates in a bounded environment

Create candidates in shadow and restrict tools to reads where possible. Shadow is an evaluation state, not proof of universal side-effect suppression. Inspect actual tool activity. Compare versions with the same test inputs and source content. Record provider/model, prompt and configuration so results are reproducible.

The public **Evaluations** page describes methodology; use the task's actual evaluation/run evidence for promotion. Jev advisory shadow work has its own access and cost/latency gate and does not replace human authority.

#### Prompt templates, datasets and the agent catalogue

Administrators manage prompt templates on **Prompt Templates**. Three panels on that screen appear only where the deployment turns them on, and each is off by default:

| Panel | Setting | What it adds |
| --- | --- | --- |
| Changes waiting for approval | `AGENTICORG_PROMPTS_MAKER_CHECKER`, or the tenant flag `prompts.maker_checker` | A template create, change, rollback or delete waits for a second person's approval |
| Evaluation datasets | `AGENTICORG_EVALS_V2_ENABLED` | Versioned tenant datasets that can be run and compared run by run |
| Compare models | `AGENTICORG_PROMPT_COMPARE_ENABLED` | One prompt run against several models side by side; these are real, billed model calls |

With `AGENTICORG_EVAL_PROMOTION_GATE_ENABLED` on (off by default), an agent that declares an evaluation gate is not promoted or resumed to active until its prompt has a stored run on the gate's dataset version that meets the gate's pass rate without regressing beyond its allowance. The **Agent Catalogue** screen lists each agent's registry card and lifecycle state when the agent registry is on (`AGENTICORG_AGENT_REGISTRY_ENABLED`, off by default); otherwise it says the registry is off in this deployment.

#### Move to a limited pilot

Agree users, volume, allowed data, hours, review coverage and rollback triggers. Choose a narrow population and a named support owner. Train operators and reviewers separately. Verify that a non-admin user can complete the documented flow with their own account.

Do not enable a provider/payment/channel action simply because read-only Q&A works. Each external action needs its own account, contract, authority, failure tests and operational evidence.

#### Expand deliberately

Measure actual results and reopened errors. Correct the shared cause when a bug affects multiple paths, then add regression cases that replay the failing user steps. Re-evaluate after changes to model, prompt, policy, document, connector or target site.

For a bank, the institution's risk, security, privacy and business owners approve rollout under their own process. AgenticOrg does not make a regulatory approval, certification or guaranteed service-level claim on the basis of this checklist.

Next: [Team adoption checklist](/docs/adoption-checklist), [BFSI onboarding](/docs/bfsi-business-onboarding).


### Security, privacy and data handling

URL: https://agenticorg.ai/docs/security-and-data
Audience: Security teams and data owners. Reviewed: 2026-10-11.

#### Start with approved data

Use synthetic records when learning. Before real data, identify the data owner, classification, purpose, allowed model/providers, retention and access. Minimize what each task receives. A document being useful to a model is not permission to upload it.

For BFSI, customer identity, financial, health and account information can require institution-specific controls. This guide explains product boundaries; it is not legal advice or proof of regulatory compliance.

#### Protect access and credentials

Use named accounts and least-powerful roles. Keep company context explicit. Store provider credentials through the approved protected form, secret manager or connector path; never in prompts, scripts, example files or screenshots.

Review API keys and delegated grants by scope, environment and owner. Rotate and revoke through the appropriate control. A machine credential is not a human session and cannot perform human-only case decisions.

#### Understand where information goes

| Path | Review requirement |
| --- | --- |
| Model and embedding calls | Provider endpoint, permitted data, retention and contractual terms |
| Knowledge extraction | File access, extracted chunks, OCR quality, replacement and deletion |
| Voice | Provider recording/retention, approved number and encrypted bounded text |
| Calls (speech intelligence, off by default) | Encrypted audio and transcript kept per tenant, the transcription engine and speech-provider credential used, spoken-data redaction, and how recordings are removed: the speech routes offer no deletion or retention setting |
| RPA | Approved domains, secret custody and screenshot/log content |
| Governed cases | Cited evidence, encrypted excerpts, decision authority and signed handoff |
| Commerce | Merchant scope, artifact freshness, public-safe projection and provider-owned execution |

AgenticOrg's controls do not automatically set the provider's retention or your bank's network configuration. Review those separately.

**Settings > Compliance & Data > Data Region** records the tenant's region (IN, EU or US). It does not move stored data or change where the hosted service runs. Residency enforcement is off by default. When a platform operator turns it on for the deployment (`AGENTICORG_RESIDENCY_ENFORCE=true`) or for one tenant (authority flag `residency.enforce`), any AI or integration provider without an active attestation for that region is refused; providers running inside the deployment need none. Administrators record attestations through `/api/v1/residency/attestations`. Confirm the deployment's actual regions with your platform owner.

#### Retention and deletion

Decide who can delete source documents, derived knowledge, retained excerpts and operational evidence. These are not identical resources. Governed-case excerpt deletion can remove retained passages while keeping references/digests and the memo. It does not silently erase every downstream copy or the institution's system-of-record obligation.

Ask the operator to verify backup/restore and erasure procedures in the actual environment. A backup configuration file is not proof that restoration works.

#### Respond to an incident

Stop affected schedules/actions, revoke compromised credentials, preserve safe references and notify the designated incident owner. Report security issues privately through [Support](https://agenticorg.ai/support) or the repository's security process. Do not open a public issue containing customer documents, tokens or exploitable tenant identifiers.

A useful incident record states time, version, resource/run reference, affected path, observed symptom and mitigation. Keep customer material in the institution's approved evidence system.

Next: [Workspace and roles](/docs/workspace-and-roles), [Audit and monitoring](/docs/audit-and-monitoring), [Self-hosting](/docs/self-hosting).


### Billing, limits and support

URL: https://agenticorg.ai/docs/billing-and-support
Audience: Account owners. Reviewed: 2026-10-13.

#### Understand separate cost sources

Hosted platform plans and external provider usage are different. Models, embeddings, calls, messaging, merchant systems and payment providers can charge independently. Self-hosting adds your infrastructure and operating costs. Do not assume an economy label means the provider is free for your account.

The [approved prospective licensing policy](/docs/licensing) has not been adopted
by a software release and does not change current Apache-2.0 rights or hosted/provider charges. Commercial
agreement inquiries go to [sanjeev@orchestrum.in](mailto:sanjeev@orchestrum.in).
Existing and new covered users require a commercialization agreement; an older
account is not an exemption. Existing hosted customers transition through the
notice and acceptance required by their contracts. Self-use remains free of a
software license fee; this does not promise free hosting or providers.

Administrators and CFOs can open the **Cost Dashboard** at `/dashboard/costs` (it has no sidebar entry). It sums the platform's own recorded USD cost per task and agent; it is not a provider invoice.

The hosted pricing page is generated from the platform's plan catalog. Use [Pricing](https://agenticorg.ai/pricing) and **Billing** in your workspace for current plan information rather than relying on a hard-coded price in a guide.

#### Review a plan

Compare agent/run/storage allowances, required connector access, identity features, support and deployment needs. Ask the account owner to verify subscription status and currency. A plan upgrade does not configure provider keys or activate every optional feature.

Before a pilot, set a provider budget, expected workload, limits and an alert owner. Start with short tasks and read-only tools. For voice, approve destinations and calling windows; for RPA, avoid unnecessarily frequent schedules.

#### Billing-console procedure

1. Open **Billing** with the account-owner/admin role.
2. Inspect the current plan and supported subscription/usage controls.
3. Review the requested change and terms before checkout.
4. Return from the billing-provider flow and confirm the recorded status.
5. If status is unclear, check the provider reference and contact support; do not repeatedly submit payment.

Platform subscription billing is separate from OACP buyer payment and merchant mandate execution.

#### Send an actionable support request

Include the affected screen/flow, safe run/case reference, timestamp and timezone, selected company context, deployed version where available, expected versus actual behavior, and steps to reproduce. State whether the issue is hosted or self-managed and whether it blocks an external action.

Do not include passwords, raw API keys, full account numbers, identity documents or unredacted provider payloads. If evidence is sensitive, arrange the approved private support channel first.

AgenticOrg is owned by **Orchestrum Technologies LLP**. Inventor / Owner: **Sanjeev Kumar**. Product contact: [sanjeev@orchestrum.in](mailto:sanjeev@orchestrum.in) or [mishra.sanjeev@gmail.com](mailto:mishra.sanjeev@gmail.com). Use the published [Support](https://agenticorg.ai/support), [Privacy](https://agenticorg.ai/privacy) and [Terms](https://agenticorg.ai/terms) pages for current policies.


### Usage and licensing

URL: https://agenticorg.ai/docs/licensing
Audience: Everyone. Reviewed: 2026-10-13.

**Status: Approved for policy publication; not adopted by a software release.**
**Legal review approval:** Received by owner attestation on 12 October 2026.
**Prepared:** 12 October 2026. No effective date or covered release has been approved.

#### Short notice

Under this policy: personal and internal use is free;
commercializing the platform requires an agreement with Orchestrum Technologies LLP.
Agreements: [sanjeev@orchestrum.in](mailto:sanjeev@orchestrum.in).

The policy covers existing and new users of covered software and Orchestrum-hosted
commercial offerings. An older account is not an exemption. Software adoption
awaits the release scope below; existing hosted customers require the contractual
transition described below, not a backdated obligation.

Current Apache-2.0 rights remain unchanged. This policy is not an additional
restriction on existing Apache-licensed software, specifications or SDKs.

#### The workable licensing model

Use mixed licensing, with an explicit boundary rather than attempting to revoke
an already published license:

| Material or service | Treatment |
| --- | --- |
| Previously Apache-licensed code and copies | Original grants remain, including commercial use |
| Eligible new Orchestrum-controlled platform material | Separate self-use/commercial-agreement license after explicit adoption |
| Published SDKs, specifications and third-party components | Retain their published licenses; no silent conversion |
| Orchestrum-operated hosting, support, reseller/OEM access or brand rights | Applicable service or commercial agreement, separate from source-code rights |
| Your business data, prompts, workflows and outputs | No ownership claim is added by this licensing policy |

The concrete candidate is
`licensing/ORCHESTRUM-SELF-USE-COMMERCIAL-1.0-DRAFT.md`; its proposed identifier is
`LicenseRef-Orchestrum-Self-Use-Commercial-1.0`. The adoption record is
`licensing/scope.json`. The text is approved for policy publication, not adoption.
The current scope has **zero covered files**, no release version and no effective
date. Owner publication and owner-attested legal approval are recorded; neither
designates code for adoption. Its reference baseline commit is a
source-review reference, **not a licensing cutoff**.

Prefer separately identifiable original modules that have not already been
distributed under Apache-2.0. Do not move old code into a new folder or change
its header and call that a new licensing right. For mixed or derived files,
document the retained material and obtain a specific rights/notice assessment.

This protects eligible new software and commercial service/brand arrangements
going forward. It does not stop someone commercializing an independent,
previously Apache-licensed implementation. Hosted plans and support can be
monetized separately without changing its source license.

#### Existing users and new users

The agreement requirement is not limited to new customers. Existing and new users
must have a written agreement with Orchestrum Technologies LLP for commercialization
of software validly covered by the new license or of Orchestrum-hosted platform
capabilities under the applicable service terms. Account age alone does not exempt
a covered commercial offering.

For existing hosted commercial customers:

1. Identify the covered commercial offering and check the current agreement.
2. Give the notice and obtain the acceptance required by that agreement and
   applicable law before changing the conditions for continued commercial use.
3. Execute a commercial agreement or amendment covering the offering. An existing
   signed agreement that already authorizes it satisfies the requirement; a duplicate
   agreement is not required merely because this notice was published.

No retroactive fees, automatic acceptance, account suspension or effective date
are created by publishing this policy. Existing executed agreements control until
validly amended or replaced. Self-use remains free of a software license fee;
hosting and provider charges are separate.

For previously distributed Apache-2.0 copies, the existing commercial permissions
remain available. An existing user may separately agree to commercial services or
additional rights, but an agreement cannot be made mandatory solely to exercise
those already-granted permissions by changing this page.

#### What self-use means

Personal use, evaluation, development and an organization's own operations would
be royalty-free for the software covered by the finalized future license. This
includes internal agents and a bank or merchant serving its own customers in its
ordinary business. Revenue from that ordinary business, selling the merchant's
own goods, or using agent output does not by itself commercialize the platform.

The proposed self-use permission would allow installing, running, copying and
modifying covered software for those purposes, retaining applicable notices.
It does not promise free hosted subscriptions, unlimited usage, infrastructure,
model inference, messaging, telephony, payment processing or third-party services.
Their applicable plans and charges remain separate.

#### What would require an agreement

Before commercially offering covered platform software or capabilities to other
parties, obtain a written agreement with Orchestrum Technologies LLP. Examples:

- Reselling or sublicensing covered software as a paid product.
- Operating paid hosted or managed platform access for third parties.
- White-labeling the platform or embedding its agent/runtime capabilities in a
  product or service sold to third parties.
- Selling third-party access to a platform-based agent service.

A consultant helping a customer operate that customer's own licensed deployment
is not automatically a platform reseller. Selling platform access as part of that
consulting service would require an agreement. Borderline arrangements should be
confirmed in writing before relying on the future license.

No price, royalty rate, exclusivity, approval, support or service level is implied.
Send the proposed offering, deployment model and intended users to
[sanjeev@orchestrum.in](mailto:sanjeev@orchestrum.in). An inquiry is not an agreement.

#### Scope of a future license

Only an explicitly identified future release and material for which Orchestrum
has the necessary licensing rights could adopt the finalized new terms. A release
manifest must identify covered files, versions and artifacts, excluded
Apache-licensed material, and third-party notices. The policy must not claim
exclusive rights over external contributions without supporting rights records.

Already-granted Apache-2.0 permissions remain in place for that material,
including commercial rights, forks and copies. Republishing the same code or
changing a footer does not withdraw those permissions. Future modifications may
have different terms only where authorized; retained Apache components still
carry their original license and notice obligations.

Third-party dependencies retain their own licenses. Protocol specifications,
published interoperability contracts, SDKs and examples must each have an explicit
release-by-release licensing decision; this proposal does not silently relicense
them. Ownership and trademark notices do not override any software license.

#### Source availability and distribution

If adopted, a license restricting commercialization would be source-available,
not an OSI-approved open-source license. Do not call it Apache-2.0 with an added
commercial restriction or advertise restricted releases as unrestricted open source.

The candidate text defines self-use, commercialization, noncommercial sharing,
data/output boundaries, proposed patent permission, trademarks, separate hosted
charges, disclaimers and a proposed notice/cure process. Publication approval is
recorded, not software adoption or a guarantee of enforceability. Source-specific
rights clearance, exact scope and release details are still required. Existing source-license
disclaimers continue to apply to existing releases.

#### Exact application to a future release

For each covered entry in `licensing/scope.json`, record the exact repository
path, SHA-256 content hash, license identifier and non-sensitive rights-clearance
reference. Keep contracts and personal/legal evidence outside the public repository.
Record the approved release version, effective date and owner/legal approval
references before changing the manifest's status to an active software adoption.

Only then apply the finalized custom-license header to the eligible new material
and publish matching package notices. Keep retained Apache notices where they
belong. Packages containing both types need an accurate mixed-license description,
not an Apache-only label or an unsupported claim of exclusive ownership.

Future contributors to that covered material must expressly agree to reviewed
contribution terms that let Orchestrum grant the intended self-use and commercial
permissions. Current Apache contribution terms do not automatically create those
rights or assign contributors' copyrights.

Do not infer eligibility from an author name or from the reference baseline's
date. Keep already Apache-distributed material outside the exclusive commercial
claim, even if its current file hash changes.

No licensing phone-home, agent transaction check, credential collection, runtime
lockout or billing change is introduced by this documentation work.

#### Before a software release adopts the license

1. Publication and legal-review approval were supplied by the owner on 12 October
   2026. Keep that approved text and its provenance distinct from source-specific
   rights clearance and software release adoption.
2. Verify copyright ownership and contributor agreements for each covered item;
   preserve grants for material Orchestrum cannot relicense exclusively.
3. Approve the exact release/file manifest, final license text and effective date.
   No effective date is implied by the preparation date above.
4. Publish the final license and changelog; align covered file headers, package
   metadata, registries, documentation, READMEs and public notices. Do not alter
   third-party or legacy-license labels.
   Update contribution/header-check instructions for the approved covered scope,
   and include the applicable license texts/notices in images and distributions.
5. Keep historic releases and their licenses accessible. Give hosted customers
   appropriate notice and obtain required contractual acceptance separately.
6. Review the website's quiet footer link for readability and discoverability;
   material terms must not be hidden or implied to be already accepted.

Until those steps are complete, the current LICENSE and applicable executed
hosted-service agreements control. Publishing this policy changes no billing, entitlements,
runtime behavior or existing license grants.

#### References

- [Apache License 2.0, sections 2, 4 and 5](https://www.apache.org/licenses/LICENSE-2.0)
- [Apache licensing FAQ](https://www.apache.org/foundation/license-faq.html)
- [Open Source Definition](https://opensource.org/osd)


### AI spend intelligence and invoice reconciliation

URL: https://agenticorg.ai/docs/ai-spend-intelligence
Audience: Administrators, finance teams and auditors. Reviewed: 2026-10-11.

#### What it answers

AI spend intelligence keeps a priced, attributed record of the AI work a deployment does and checks it against what each provider invoices. This guide is for the administrators who set it up and reconcile the figures, and the auditors who read and check them. The CFO role and the other domain roles are not readers of tenant-wide or commercial figures (see [Who can read what](/docs/ai-spend-intelligence#who-can-read-what)).

| Question | Where the answer comes from |
| --- | --- |
| Which business unit, department, team or cost centre used which model, and what did it cost in rupees? | Usage records and daily rollups |
| How much of the month's spend is not attributed to the organisation, and why? | Coverage: the attributed share, the unattributed share and its reasons |
| Does each provider's invoice agree with what was metered, priced at the rates you agreed? | Invoice import and reconciliation within the 1% match tolerance |
| Does the month meet Gate 1: attributed, priced, converted to INR and reconciled? | The Gate 1 status, read together with the month's meter gaps |

The feature is off by default, and phase 1 is API-only: there is no spend screen in the app. Every request in this guide goes to `/api/v1/spend/...` with an authenticated session, and the values in the examples are illustrative. The figures are what was metered and priced with the rate cards you entered. They are not a provider's bill, a tax figure or an accounting entry. Usage records are a separate source: the existing cost ledgers, the model-call records and the screens that read them stay as they are, and `GET /spend/coverage/ledgers` sets the two side by side with the expected differences listed.

#### Turning it on

Spend intelligence is controlled by one deployment setting. While it is off, `GET /api/v1/spend/status` answers with `enabled: false`, every other spend address answers 404 `spend_disabled` before the request body is read, nothing is metered or written, and no existing behaviour changes.

| Setting | Default | What it controls |
| --- | --- | --- |
| `AGENTICORG_SPEND_INTELLIGENCE_ENABLED` | off | The whole feature |
| `AGENTICORG_SPEND_REPORTING_TIMEZONE` | `Asia/Kolkata` | The reporting day: FX lookup, rollups, coverage and the Gate 1 attribution month |
| `AGENTICORG_SPEND_PROVIDER_BILLING_TIMEZONES_JSON` | empty | The zone each provider closes its billing day in; it dates rate cards, commitments and the reconciliation month |
| `AGENTICORG_SPEND_SWEEPS_ENABLED` | on | The scheduled spend jobs (partition check, FX settlement, commitment recompute, storage samples, GPU allocation, job sweep); no effect while the feature is off |
| `AGENTICORG_SPEND_GPU_POOLS_JSON` | empty | Standing in-house GPU pools whose node hours are shared out to the calls that used them |
| `AGENTICORG_SPEND_AUDIT_COMMERCIAL_FILTER` | on | `GET /audit` hides the audit rows of rate cards, commitments, invoices, reconciliations and spend jobs from readers other than an administrator or auditor, whether the feature is on or off (see "Who can read what" below); off restores the previous `GET /audit` for every reader |

The tables come from four migrations, `v6z79_spend_reference`, `v6z80_spend_usage`, `v6z81_spend_gpu` and `v6z82_spend_reconciliation`. Apply them before the release that turns the switch on; strict runtimes do not create tables at start-up (see [Self-hosting](/docs/self-hosting)). With the feature on, a deployment refuses to start when the reporting zone or a provider billing zone cannot be loaded, or when the GPU pool setting does not parse.

**Who can write.** Every change (reference data, imports, maintenance jobs, invoice imports, reconciliations and acceptances) needs a tenant administrator signed in as a person. The server checks the administrator scope and then confirms an active administrator of the tenant in the database. API keys and agent tokens are refused, and `approvals:write` alone, which developers and domain heads hold, is not enough. Each change is audited with the acting administrator's id in the same transaction. Metering can be paused for one tenant with the feature flag `spend.metering_paused`; paused usage is not written and is counted as a `paused` meter gap.

```flow
Apply the migrations | Run v6z79 to v6z82 in the release before the one that turns the switch on.
Turn on the switch | Turn on the spend switch from the settings table above and check that the reporting and billing zones load.
Confirm the status | GET /api/v1/spend/status answers enabled true and says whether this process's writer started.
Load reference data | Build the organisation tree, map sources, then enter rate cards, FX rates and commitments.
Watch coverage | Read coverage and meter gaps; add mappings and rate cards, then re-attribute and restate the records already written.
Reconcile the first month | Import each provider's invoice, reconcile the month and read the Gate 1 status.
```

#### Setting up the reference data

Reference data is what spend is measured against. Every kind can be written one row at a time, and the organisation tree, mappings, rate cards and FX rates can also be imported from a CSV or JSON file (`POST .../import`, at most 2 MiB and 5,000 rows). Add `dry_run=true` to an import to see exactly what it would create, update or reject without writing anything. The examples below omit the `Authorization` header that every request carries.

### Organisation tree

A node has your own code (such as `CC-4120`), a name, a kind, a parent and an optional owner. Only a group may be a root. A node is never deleted: setting `active` to false deactivates it, and its children keep rolling up through it.

| Kind | May sit under |
| --- | --- |
| `group` | nothing (a root) or a group |
| `business_unit` | a group or a business unit |
| `department` | a group, a business unit or a department |
| `team` | a department or a team |
| `cost_centre` | a group, a business unit, a department or a team |

```http
POST /api/v1/spend/org-nodes
Authorization: Bearer <administrator session token>
Content-Type: application/json

{"code":"CC-4120","name":"Card disputes","kind":"cost_centre","parent_code":"DEPT-CARDS"}
```

### Source mappings

A mapping ties a spend source to a node, a product line and a use case. Sources are an `agent`, a `workflow`, an `application` (such as `chat`, `voice`, `knowledge` or `documents`) or a legacy `cost_center` or `department` label that agents carry today. A mapping is turned off with `active: false`, never deleted.

```http
PUT /api/v1/spend/mappings
Content-Type: application/json

{"source_type":"agent","source_ref":"<agent id>","org_node_code":"CC-4120","product_line":"cards","use_case":"dispute-triage"}
```

Attribution is worked out on the server from the agent's configuration, these mappings and the tree. The department, cost-centre, business-unit and use-case labels a caller sends with a run are ignored, so a caller cannot charge its usage to someone else's cost centre.

### Rate cards in rupees or the provider's currency

A rate card prices one provider, usage type, model, unit and source (`contract` or `list`) from `effective_from` until `effective_to`, in the provider's billing dates. A rate change is a new card with a later start, so history keeps the rate of its day; two active cards of one key may never overlap.

```http
POST /api/v1/spend/rate-cards
Content-Type: application/json

{"provider":"openai","usage_type":"llm_tokens","model_sku":"example-chat-model","unit":"1m_input_tokens","unit_price":"212.50","cached_unit_price":"106.25","currency":"INR","effective_from":"2026-10-01","source":"contract","reference":"MSA-2026-17"}
```

- **Which card prices a call.** A model-specific card comes before a provider default; within one level, a cached-token price comes before the plain input price; then a contract card comes before a list card; then the latest start.
- **Cached and batch prices.** An input-token card may carry a cached-input price. Any card may carry a batch discount percentage, but phase 1 records carry no batch flag, so the discount is stored but not yet applied in metering, price quotes or reconciliation.
- **Volume tiers.** A card may carry up to 20 tiers, `graduated` or `all_units`. Usage is priced at the base price; the tiers are applied per contract and billing month in reconciliation.
- **Adding a card later.** A new card prices usage metered from then on. Records already written stay unpriced, or fallback-priced, until you run `POST /spend/usage/restate` for the provider and its billing days (at most 92 per job, with a reason); `include_unpriced` is on by default, so the job re-prices those records with the cards as known now.
- **No card.** Model tokens fall back to the deployment's list prices in USD and are marked as fallback-priced. In-house models, embeddings, OCR and Whisper price at zero unless you add a card; in-house model serving is charged through GPU node hours. Anything else with no price is **unpriced**: it has no amount, never zero, and is counted.
- **Corrections.** A card that has priced usage changes only through `POST /spend/rate-cards/{card_id}/correct` with a reason. The correction queues a restatement of the records the old card priced, in the same transaction.

`GET /api/v1/spend/price?provider=openai&usage_type=llm_tokens&unit=input_token&quantity=120000&model=example-chat-model&on=2026-10-15` prices a usage the way metering will, so you can check a card before usage arrives.

### FX rates to INR

Rates are kept per currency and date as the rate to INR. A record converts on its reporting date. With no rate that day (a holiday or a rate not yet published), the latest earlier rate converts and the record is marked `fx_estimated`; with no rate at all the record is `unconverted`. A new or changed rate queues an FX settlement that converts those records again with the rate of their day.

```http
PUT /api/v1/spend/fx-rates
Content-Type: application/json

{"rate_date":"2026-10-01","currency":"USD","rate_to_inr":"84.10","source":"reference"}
```

### Commitments

A **quantity** commitment names a provider, usage type, optional model, card unit and quantity, and may carry an overage price. A **money** commitment names a provider, an optional usage type and an amount in a currency. Drawdown is counted from usage records in time order by a recompute job; a record past the capacity is flagged as overage, and the overage price is applied in reconciliation, not on the record.

```http
POST /api/v1/spend/commitments
Content-Type: application/json

{"provider":"openai","kind":"quantity","usage_type":"llm_tokens","model_sku":"example-chat-model","unit":"1m_input_tokens","committed_quantity":"500","period_start":"2026-10-01","period_end":"2027-04-01","overage_unit_price":"240.00","overage_currency":"INR"}
```

#### What gets metered

Each billable quantity in one unit becomes one usage record, with the same pricing, attribution and daily rollups whatever produced it.

| Usage | Record unit | Where it is counted |
| --- | --- | --- |
| Model calls | input, cached input and output tokens | Every model call through the router and the agent graph, plus four direct callers; one estimated `token` record when a provider does not split its count |
| Embeddings | embedding tokens, estimated from characters | Knowledge ingestion, re-indexing, search and RPA ingestion |
| OCR pages | pages | Document processing, knowledge uploads and ingestion that extracted a file itself |
| Speech minutes | audio minutes | Each transcription by the in-house Whisper engine or Deepgram, metered when the engine returns, so a later redaction, encryption or save failure does not lose minutes already transcribed |
| Priced tool calls | calls | A successful connector tool call, only when a rate card prices that tool |
| Storage | GB-days | A daily sample of each tenant's knowledge, document, document-processing and recording storage |
| In-house GPU | GPU node hours | Each closed pool hour, shared over the calls of the pool's models by tokens |

A record holds identifiers, counts and amounts only, never a prompt, a response, a document or customer data. It is append-only: its event fields never change, and only audited maintenance jobs revise its price, FX, attribution or commitment fields.

**The meter does no database work or waiting on the call path.** The hook builds the call's usage in memory and puts it on a bounded in-process queue. If metering fails, the failure is logged and counted and the call carries on unchanged. A writer thread in each process writes the queue in batches; a batch it cannot write is handed to a retry task with the same keys, so a retry never writes a record twice. Usage that still cannot be written is counted as a meter gap (`GET /spend/gaps`), and backfill can recreate model-call records from the model gateway's records while those exist.

**How attribution is chosen.** The first rule that matches wins and is stored on the record as its `attribution_path`:

| Situation | Order of rules |
| --- | --- |
| A call made by an agent | the agent's mapping; its legacy cost centre (mapping, then a node with the same code); the application's mapping |
| A workflow step with no agent | the workflow's mapping; the application's mapping; the initiating user's department |
| Anything else | the application's mapping; the initiating user's department |

A legacy label that names no node stops there: the record is kept and counted as unattributed with the reason `unknown_label`, never moved to a broader mapping. The business unit stored with a record is the nearest business unit at or above its node.

#### Reading spend

| Read | Window | What it returns |
| --- | --- | --- |
| `GET /spend/usage` | up to 31 days | Records a page at a time, filtered by usage type, provider, node, agent, unattributed or unpriced |
| `GET /spend/rollups` | up to 366 days | Sums per day or per one dimension (node, business unit, use case, provider, model, agent and more), per currency and in INR |
| `GET /spend/coverage` | up to 366 days | Per day and for the period: the attributed and unattributed shares, unpriced and unconverted records, pending FX and gaps by reason |
| `GET /spend/gaps` | up to 92 days | Usage that could not be metered, by day, usage type and reason |
| `GET /spend/coverage/ledgers` | up to 31 days | Usage beside the existing cost ledgers and model-call records, with the expected differences |

The **attributed share** is the INR amount attributed to a business unit, department, team or cost centre over the whole INR amount. Attribution to a `group` node is reported separately as `group_share` and does not count. Records with no INR amount (unpriced or unconverted) count only in the record-count share and are listed beside it, so their volume stays visible. Shares are shown to six decimals and rounded so they never look better than they are.

| Unattributed reason | What it means | What to do |
| --- | --- | --- |
| `no_mapping` | No rule matched | Add a mapping for the agent, workflow or application |
| `unknown_label` | A legacy cost-centre or department label names no node | Map the label or create a node with its code |
| `inactive_node` | The matched node is deactivated | Reactivate it or move the mapping |
| `no_source` | A system call with no user | Map the application |
| `resolver_failed` | A database failure during resolution | Check the logs; the record was still written |

After adding mappings or nodes, `POST /spend/usage/reattribute` resolves the still-unattributed records again. Long operations like this one are maintenance jobs: the request answers `202` with a job id, one job of a kind runs at a time per tenant, and `GET /spend/jobs/{job_id}` reports its status and result. The other jobs rebuild rollups, backfill model calls, restate prices, settle FX and recompute commitments.

#### Reconciling invoices

**Import the invoice.** `POST /spend/invoices/import` takes one provider's invoice or billing export for one billing month, in the provider's own billing zone. An invoice is stored whole or refused whole: one bad line refuses the file with 422 `invoice_rejected`, listing every refused line and its reason, because a partial invoice would reconcile against a wrong total.

```http
POST /api/v1/spend/invoices/import?provider=openai&period=2026-10&invoice_ref=INV-2026-10-0042&currency=USD&dry_run=true
Content-Type: multipart/form-data

file: invoice-2026-10.csv
```

```csv
line_kind,usage_type,model_sku,unit,quantity,amount
usage,llm_tokens,example-chat-model,1m_input_tokens,412.5,1031.25
usage,llm_tokens,example-chat-model,1m_output_tokens,96,960
tax,,,,,358.43
```

| Line kind | In the comparison |
| --- | --- |
| `usage` (the default) | Yes |
| `credit`, `tax`, `fee` | No, reported beside it |
| `commitment` (shortfall or prepaid charges) | No, reported beside it |

A second current invoice with the same reference is refused unless `replace=true`, which supersedes the earlier one; both are kept. Several references for one provider and month, such as two accounts, are summed. A month holds at most what a reconciliation can store: an import that would take the month's current invoices past that is refused with 413 (`too_many_rows`, `period_amount_too_large` or `period_quantity_too_large`), dry runs included.

**Run the reconciliation.** `POST /spend/reconciliations` with `{"provider":"openai","period":"2026-10"}` compares the provider's month with its current invoices and answers the run with its items. Only usage billed to the tenant's own key is compared (usage whose paying account could not be inferred is included and counted); usage on the platform's key is reported separately, and in-house serving, storage and GPU hours have no provider invoice. Each item carries two figures in the invoice currency:

- **stored**: the amounts as metered;
- **re-priced**: the same usage priced again with the cards in force on each billing day as known now.

The month's volume tiers and any commitment overage are worked out for each figure from its own base: the stored figure from the cards that priced the records, the re-priced figure from the cards in force now. The run reports both adjustment totals (`stored_adjustments_amount`, `repriced_adjustments_amount`).

An item is within tolerance only when both figures are known and each is within 1% of the invoice. Otherwise it needs review. So a card entered or corrected after metering leaves its items needing review until a restatement brings the records to the contracted rates. A run goes `stale` when anything it read would now read differently: late records, a card, an alias, an FX row or the month's invoices.

**Accept a difference.** An item that needs review can be accepted with a reason of 10 to 500 characters (`POST /spend/reconciliations/{reconciliation_id}/items/{item_id}/accept`). The acceptor must be an active tenant administrator other than whoever imported one of the run's invoices (409 `same_actor`); this is the maker-checker rule, and a tenant with a single administrator cannot accept anything. Every acceptance is audited with the reason, both variances and the actor. An accepted difference is recorded, but it does not meet Gate 1.

```flow
Check the month's reference data | Confirm the month's rate cards, commitments and FX rates are entered and settled. | Owner: Spend administrator | Human decision: Decide whether any contract change dated inside the month needs a correction and restatement first. | If blocked: Unpriced records stay listed in coverage until a card covers them and a restatement re-prices them; unconverted records convert when the settlement a new FX rate queues has run.
Review coverage | Read the month's coverage and meter gaps and clear unattributed spend with mappings and re-attribution. | Owner: Spend administrator, reviewed by an auditor | Human decision: Agree which unattributed reasons are fixed now and which are explained. | If blocked: A share below 0.98 or any unpriced record keeps attribution unmet.
Import the provider invoice | Dry-run the invoice file, then import it for the provider's billing month. | Owner: Administrator A, the importer | Human decision: Confirm the invoice reference, currency and billing month against the provider document. | If blocked: 422 invoice_rejected lists every refused line; nothing is stored until the file is corrected.
Run the reconciliation | Reconcile the provider's month and read each item's stored and re-priced variance. | Owner: Spend administrator | Human decision: Decide whether a difference is a metering, pricing or invoice question. | If blocked: 409 invoice_missing when the month has no current invoice; 422 currency_mismatch when its invoices differ in currency.
Resolve or accept differences | Correct cards and restate, or accept an explained difference with a written reason. | Owner: Administrator B, not the importer | Human decision: Accept only a difference that is explained and evidenced outside the system. | If blocked: 409 same_actor when the importer tries to accept; the item stays open.
Read the Gate 1 status | Request the month's gate and meter gaps and keep both responses with the month's evidence. | Owner: Auditor or administrator | Human decision: Treat the month as reconciled only when gate_met is true and the meter gaps are explained. | If blocked: Missing, stale or accepted reconciliations are listed by provider and keep the gate unmet.
```

#### The Gate 1 status

`GET /api/v1/spend/gate?period=2026-10` answers whether a month meets Gate 1. It is met only when both halves are met.

| Half | Met when | Reasons or lists when not met |
| --- | --- | --- |
| Attribution (the reporting month) | The attributed share is at least 0.98, and no record is unpriced, unconverted or waiting for an FX rate | `below_target`, `no_priced_usage`, `unpriced_usage`, `unconverted_usage`, `fx_pending` |
| Reconciliation (each provider's billing month) | Every provider with a current invoice or tenant-billed priced usage has a current, fresh run within tolerance | `missing_reconciliations`, `stale_reconciliations`, `accepted_exceptions` |

```json
{
  "period": "2026-10",
  "gate_met": false,
  "attribution": {"attributed_share": "0.991204", "target": "0.98", "met": true, "reasons": []},
  "reconciliation": {"met": false, "missing_reconciliations": ["anthropic"], "stale_reconciliations": [], "accepted_exceptions": [], "tolerance_pct": "1.00"},
  "backfill_source": "model_gateway_records"
}
```

The rules are deliberately strict: no unpriced record is allowed, group attribution does not count, an accepted difference does not meet the gate, and an item needs both figures within 1%. Shares are shown rounded toward zero and variances away from it, while the verdicts use the exact values, so a share of 0.979996 is shown as `0.979996` and is not met. An invoiced provider with no metered records is listed too, because it can point to a broken hook, a provider-name mismatch or usage on a key the tenant did not pay for. The response repeats `backfill_source`, so you know whether lost model-call writes can still be recreated before you trust the month.

Gate 1 does not check everything. Meter gaps are reported beside the attribution figures but do not fail the gate: usage that could not be written or was lost at shutdown, tool calls that no card prices, and usage paused for the tenant with `spend.metering_paused`, which is not in the share at all. Storage, in-house GPU hours and in-house model serving have no provider invoice, so they are never reconciled. Read `GET /spend/gaps` for the month before you treat its figures as complete.

```flow
Read the reasons | Start from attribution.reasons and the three reconciliation lists in the gate response.
Fix attribution | Add mappings or nodes, then run re-attribution for the month.
Fix prices and rates | After adding a card, run POST /spend/usage/restate for the provider's billing days (at most 92). A correction queues its own restatement, and a new FX rate queues its settlement.
Re-run reconciliation | Reconcile every missing or stale provider again after the records change.
Read the gate again | Request the gate for the same month and compare it with the earlier response.
```

#### Who can read what

Reads need the `audit:read` scope. Beyond that, one rule decides what each reader sees.

| Read | Administrator (a person) | Auditor (a person with unrestricted domains) | Anyone else |
| --- | --- | --- | --- |
| Usage records and rollups | Every record and row | Every record and row | Only records of agents they may see, and records with no agent; contract terms and user ids hidden; no rate-card or commitment grouping |
| Coverage, meter gaps, jobs and GPU allocations | The whole tenant | The whole tenant | Refused, 403 `tenant_wide_read_refused` |
| Rate cards, commitments and price quotes | Yes | Yes | Refused, 403 `commercial_read_refused` |
| Invoices, reconciliations and the Gate 1 status | Yes | Yes | Refused, 403 `commercial_read_refused` |
| Changes, imports, jobs and acceptance | Yes, signed in as a person | No | No |

"Anyone else" includes the CFO role and every other domain role, and machine credentials without the administrator scope. A finance team reads coverage, reconciliations and the gate through a person with the auditor or administrator role. Under the agent visibility rule a reader sees records with no agent, records of shared agents in their domains (every shared agent, for a machine credential) and records of their own personal agents. Tenant-wide figures are refused rather than filtered, because a filtered total would let a reader work out other agents' spend by comparing two views. Rate cards, commitments, prices, invoices, reconciliations and the gate are for a human administrator or auditor only: an API key or agent token is refused them whatever scopes it holds, since machine credentials can hold `audit:read` through agent grants. The audit rows of those writes and of spend jobs carry the same figures, so `GET /audit` hides them from the same readers, also after the feature is turned off, since audit rows are kept. A deployment can opt out with `AGENTICORG_SPEND_AUDIT_COMMERCIAL_FILTER=false`, which shows those rows to every audit reader again, as before.

#### What is not in phase 1

- **No spend screen.** Phase 1 is API-only. The app's existing cost views, such as the Cost Dashboard at `/dashboard/costs` (administrators and CFOs; it has no sidebar entry), read the existing cost ledgers, not these usage records.
- **No spend dashboards, budgets, alerts, forecasts, statements or month close.** These belong to later phases; freezing closed months and statements belong to phase 2. Spend intelligence does not block or throttle a call because of its spend.
- **Some usage is not metered:** the embedding backfill command and seed data, the voice runtime's own speech-to-text and text-to-speech outside the speech store, and the tool gateway's own completion path.
- **No batch flag on records.** Reconciliation re-prices every group as non-batch usage.
- **No HTTP write for GPU hours.** Standing pools come from the deployment setting and metered hours from an operator command, because a tenant administrator must not set a cost shared by every tenant.

For the full behaviour, error codes and limits, read the [spend intelligence reference](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/finops/spend-intelligence.md).

Next: [Model Gateway](/docs/model-gateway), [Audit and monitoring](/docs/audit-and-monitoring), [Workspace and roles](/docs/workspace-and-roles), [API, SDK and MCP](/docs/api-sdk-mcp).


### Troubleshooting by symptom

URL: https://agenticorg.ai/docs/troubleshooting
Audience: Everyone. Reviewed: 2026-10-11.

#### Start with the smallest failing layer

Record the exact screen, timestamp, company, safe run reference and error code. Separate sign-in, permissions, model, knowledge, connector, workflow and provider issues. Changing all configuration at once makes the cause harder to find.

#### Symptom checklist

| Symptom | First checks | Safe recovery |
| --- | --- | --- |
| Cannot sign in | Correct deployment, email/invitation, expired session | Use password recovery or administrator identity support |
| Menu missing / `403` | Assigned role and route/tool scope | Have the owner grant the required permission; no shared admin login |
| Data missing after company switch | Selected company, resource ownership, binding | Return to authorized context and re-test; do not copy another company's IDs |
| Model credential missing | Provider/kind, tenant/company, model ID | Configure the correct credential and test a short task |
| Overload / rate limit | Provider incident, quota, concurrency | Bounded retry/backoff or approved model routing |
| Connector appears configured but fails | Upstream scope, secret binding, API contract, health age | Perform a bounded read test and correct configuration |
| Document upload fails | Supported type/limits, corruption, extractable text | Use the original supported file or a cleaner scan |
| OCR text is wrong | Orientation, language, scan quality, reading order | Compare against original; correct source or request manual review |
| Search has no result | Extraction/indexing, embedding availability, scope | Test a known phrase and the retrieval service separately |
| Workflow waits | Approval/event/wait step, worker availability | Review the waiting condition; do not bypass required approval |
| Workflow runs twice | Trigger/retry history, idempotency | Confirm external effects before retrying |
| Voice call has no reply | Callbacks, signature, mapped active agent, model | Inspect provider status and runtime health; no unsigned fallback |
| RPA times out | Target changes, session, selectors, approved domain | Pause schedules and revalidate the script in a test environment |
| Commerce answer is stale | Source sync, artifact TTL, revocation and merchant state | Refresh through the supported path; do not promise final inventory/price |
| Case decision refused | Current version, issuer configuration, distinct approvals | Resolve the exact reason and request a current decision |
| A screen says a service is off, or `idp_disabled`, `conversation_disabled` or `spend_disabled` | The service's deployment setting is off (the default) | Ask the platform owner whether it should be on; this is configuration, not an empty result |
| Run refused with `guardrail_blocked` / `E1016` | A guardrail rule at that stage blocked it | Review the rule with its owner on the Guardrails page; do not reword input to get past it |
| `423` or a tool result with `operator_override` / `E1013` | An operator halt or throttle covers the model, agent, workflow or tool pipeline | Ask the administrator who placed it; do not work around it |
| `409` "Agent is paused" | The agent is paused and the deployment refuses paused agents (`AGENTICORG_PAUSED_AGENTS_REFUSED`, off by default) | Have the owner resume the agent, or use another active agent |
| Run stopped with a `limit` block | The agent's own step, duration or tool-call limit, or its loop rule, applied while `AGENTICORG_RUNTIME_LIMITS_ENABLED` is on (off by default) | Review the limits and the repeated tool calls before running it again |
| Approval decision returns `409` | You already voted on the item, or its policy changed while it waited | See [multi-person approval rules](/docs/approvals#multi-person-approval-rules) |
| `403` `human_session_required` | An API key or agent token tried a governed-case action reserved for a person | Sign in as the named person |

#### Distinguish refused, failed and unavailable

Refused means a boundary prevented the action. Failed means the attempted path did not complete. Unavailable can mean a provider capability is absent or a tenant feature is disabled. None should be turned into a fabricated success.

`governed_cases_disabled` is feature configuration; `decision_service_not_configured` is an issuer dependency; `case_changed` means existing decision evidence is no longer current. Do not edit an underlying record to bypass these conditions.

#### Reproduce safely

Use a synthetic record with the same role, company, source version and input shape. First verify the standalone provider/model/knowledge path, then the agent, then the workflow/channel. A successful admin test does not validate an operator's permissions.

If production customer data is required to diagnose the problem, use the organization's approved private evidence channel. Screenshots can contain sensitive fields; redact before sharing.

#### Escalate with useful evidence

Send expected versus actual behavior, reproduction steps, safe references, environment/version and attempted recovery. State whether a payment, email, account change or other external action may already have happened. Never send raw tokens or credentials.

When an external effect is ambiguous, pause and confirm with the system of record. A retry that makes the UI green but duplicates a customer action is not a fix.


### Seller and buyer commerce with OACP

URL: https://agenticorg.ai/docs/commerce
Audience: Merchants and bank merchant-service teams. Reviewed: 2026-10-02.

#### The end-to-end ownership model

AgenticOrg runs seller/buyer agents and their skills, knowledge and approved integration paths. Grantex supplies trust, policy and canonical artifact authority. Shopify or another merchant system remains the operational source of truth. Banks, fintechs, providers and POS systems own payment, mandate and fulfillment execution.

For a bank-led pilot with explicit owners, human decisions and blocked paths,
see the [merchant-services process map](/docs/bfsi-merchant-services#process-map).

```flow
Merchant setup | Configure the Seller Commerce Agent and merchant-scoped sources/channels.
Shopify read-only sync | Fetch real products, variants, images, price and inventory snapshots with approved access.
Grantex authority | Send the bounded authority request and obtain validated artifacts.
AgenticOrg cache | Persist artifacts with scope, source, freshness, TTL and revocation posture.
Buyer conversation | Answer through configured web/agent/channel bridges from supported evidence.
Prepared handoff | Ask the authoritative provider, merchant or POS path to confirm its own action.
```

#### Merchant setup checklist

Open **Commerce Runtime** with an administrator or merchant role. Prepare the merchant identity/reference, source system, owner, catalog scope, approved channels, publishing state and provider/POS references. Review the available form and onboarding packet before requesting authority.

For Shopify, obtain the reviewed Admin API access and webhook configuration from the merchant's authorized administrator. Use least-powerful read scopes and protected merchant credential custody. No scraping is needed for the supported Shopify path.

Synchronize a bounded catalog and compare SKU/variant, image, amount/currency and inventory timestamp with Shopify. Confirm a signed webhook is rejected when invalid and accepted only under the configured binding. Webhook receipt alone does not prove catalog freshness; inspect the resulting source snapshot.

#### Ask useful buyer questions

For merchant setup through a third-party buyer app and the Plural payment
boundary, follow the [guided seller A2A journey](/docs/seller-a2a-commerce-journey).
To watch a buyer agent that is **not** hosted on AgenticOrg talk to a
synthetic seller over real A2A HTTP+JSON, use the
[external buyer demo](/docs/external-buyer-a2a-demo). It shows catalogue
browsing, source/freshness labels, purchase refusal, and token revocation.
It does not process a payment.

Try `Which variants of this item are available in the latest snapshot?` and `What source and timestamp support that price?`. Verify the response is merchant-scoped, source-grounded and explicit about stale or unsupported facts. Cached authority can support non-binding Q&A without routing every message through Grantex.

Do not promote stale snapshots into final price, stock, delivery, tax, return or warranty promises. Prepared purchase output is not an order confirmation or paid state.

#### Protocols and channels

The runtime includes bounded protocol-adapter payloads and web/MCP/OpenAPI/A2A/WhatsApp/Telegram bridge routes. Client configuration, provider credentials, platform/marketplace approval and merchant publishing are separate dependencies. A UCP/ACP/schema.org payload does not automatically list a merchant in ChatGPT, Gemini or another marketplace.

Current WooCommerce/ERP/PIM/OMS/WMS/custom-source configuration does not have universal runtime parity with Shopify. Treat each as an integration project until its adapter is implemented and validated.

#### Payments and offline POS

Plural/Pine capability verification records provider-owned, non-sensitive capability evidence. It is not a completed payment or mandate. A human sets up and authorizes payment relationships with the fintech/provider under its own process.

Offline POS handoff means a bounded interaction with a physical-store/POS confirmation path; it does not mean unlimited offline financial authority. Provider/POS/merchant evidence remains authoritative. AgenticOrg does not execute OACP capture, refunds, holds, shipping or order creation merely from cached artifacts.

Public discovery remains off unless explicitly enabled through platform and merchant settings. Readiness, certification and public standardization are not implied by these routes.

Next: [BFSI merchant-services playbook](/docs/bfsi-merchant-services), [API and agent clients](/docs/api-sdk-mcp).


### External buyer and seller A2A demo

URL: https://agenticorg.ai/docs/external-buyer-a2a-demo
Audience: Merchants, developers and partner integrators. Reviewed: 2026-10-02.

#### See an outside buyer talk to a seller

This walkthrough uses a synthetic local merchant. The buyer is a standalone
Python process, not an AgenticOrg buyer agent. It speaks the A2A v1 HTTP+JSON
message protocol to an AgenticOrg Seller Commerce Agent. A real external
client needs merchant-issued access; knowing an Agent Card URL is not enough.

```flow
Create a local seller | Three synthetic products and their price/inventory snapshots are placed in a development database.
Add source evidence | A local catalog cache record is linked to the exact connector evidence reference.
Approve one buyer | A tenant/merchant/seller/buyer-scoped credential is issued to a separate process.
Ask over A2A | The buyer discovers the card and sends catalog and product questions over HTTP.
Respect the boundary | A purchase request is refused; no order, payment or hold is created.
Revoke and clean up | The buyer receives HTTP 401 after revocation and temporary rows are removed.
```

#### What the buyer sees

| Synthetic product | Price snapshot | Quantity snapshot |
| --- | ---: | ---: |
| Canvas Tote | INR 1299 | 7 |
| Ceramic Mug | INR 499 | 12 |
| Pocket Notebook | INR 249 | 20 |

The buyer asks to see this catalogue, then asks
about the tote. The seller gives a price and inventory **snapshot** with a
freshness label and says that final price needs merchant confirmation. These
are local teaching fixtures, not merchant offers.

When the buyer asks to buy two totes, the seller refuses transaction
execution. That is the correct result for this A2A question route. An answer
cannot reserve stock, collect money, or create a confirmed order. For a real
purchase, the merchant system and authorized fintech/payment rail must
confirm their own outcomes through separate approved integration steps.

#### Try it on a development stack

Apply local migrations and start the development API with local PostgreSQL
and Redis. From the repository root, with local `AGENTICORG_ENV`,
`AGENTICORG_DB_URL`, and `AGENTICORG_REDIS_URL` configured, run:

```powershell
python -m examples.a2a_commerce_demo.run_demo `
  --base-url http://127.0.0.1:8000 `
  --confirm-local-synthetic
```

The runner rejects production or non-local targets. It keeps the buyer token
out of output, revokes it after the questions, and removes its synthetic
seller, evidence, and cache records. Read the [full local demo guide](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/a2a-commerce-demo.md)
for setup and expected results.

#### Taking a real merchant further

The real path uses authorized Shopify read-only sync, Grantex-issued and
verified OACP artifacts, an AgenticOrg cache, merchant-scoped buyer access,
and an external A2A client configured for the endpoint. Do not substitute
this synthetic record for signed authority. A2A interoperability is not a
promise that every vendor automatically discovers this seller. Payment and
mandate execution are owned by their fintech/provider; AgenticOrg's current
A2A seller conversation is non-binding.

Next: [Guided seller-to-buyer integration](/docs/seller-a2a-commerce-journey),
[Commerce guide](/docs/commerce), [API and A2A integration](/docs/api-sdk-mcp).


### Seller commerce with an outside A2A buyer

URL: https://agenticorg.ai/docs/seller-a2a-commerce-journey
Audience: Merchants and third-party buyer-agent integrators. Reviewed: 2026-10-01.

#### What this journey proves

An outside buyer agent can ask an AgenticOrg Seller Commerce Agent about a merchant's products over authenticated A2A v1 HTTP+JSON. The buyer can run in a consumer app such as Muse, Instinct or Dots, or in any other service that can make this A2A request. Those names are examples of possible clients, **not** claims of a built-in plugin, vendor partnership, verified client identity or automatic discovery.

The working seller question path is **non-binding**. It can return source-labelled product and inventory snapshots, or refuse. It cannot create an order, hold stock, collect money or create a Pine Labs Plural mandate. A complete paid purchase additionally requires merchant and provider integration, human authorization where required, provider confirmation, order creation and reconciliation. Do not tell a buyer they have purchased until those authoritative confirmations exist.

**Who can operate this journey.** Merchant staff provide product, source-system and payment-provider approvals. An AgenticOrg **tenant administrator** performs the protected Runtime Actions, connector credential/sync, artifact issuance, capability verification and outside-buyer access issuance described below. The `merchant` role can manage merchant configuration, but it cannot perform those admin-only actions. Arrange the administrator handoff before starting the checkpoints.

```flow
Merchant | Configure the seller, source system, channel approvals and provider reference in AgenticOrg.
Shopify | Sync the merchant's products, variants, prices and inventory read-only.
Grantex | Issue scoped OACP authority artifacts; AgenticOrg validates and caches them.
Buyer app | Receive merchant-approved access and connect to the A2A v1 seller endpoint.
Seller agent | Answer product questions from fresh cached evidence; refuse purchase execution.
Plural/P3P | Verify capability, then use separately approved provider and merchant paths for real authorization and settlement.
```

#### Transaction map: from question to a real sale

The interactive map above lets you select an illustrative buyer app and inspect each message. Its selected app name changes the diagram, **not** the system integration. The same merchant-scoped A2A rules apply to any external buyer implementation. A consumer app operator must explicitly configure the seller endpoint and protect its merchant-issued credential.

| Hop | Who talks to whom | Buyer-visible outcome | Current state |
| --- | --- | --- | --- |
| 1 | Outside buyer to AgenticOrg seller | The buyer can discover a generic card and use approved seller access. | Available with merchant-scoped credential. |
| 2 | Seller to buyer, using cached Shopify/Grantex evidence | A product answer includes source and freshness; it is not a final offer. | Available, non-binding. |
| 3 | Buyer to seller: "buy this" | The seller refuses execution and can point to a separate prepared handoff. | Available refusal; no order or stock hold. |
| 4 | AgenticOrg verifier to Plural/P3P | Capability evidence says whether a provider-owned path may be available. | Available separately; not a charge or mandate. |
| 5 | Buyer to provider authorization | The buyer reviews terms and authorizes with an approved provider flow. | Requires merchant/provider integration; not wired through the current A2A seller route. |
| 6 | Provider outcome to merchant order system | The buyer sees confirmed only after payment and order/inventory evidence agree. | Requires verified callbacks, merchant execution and reconciliation. |

**Authority boundary.** The third-party buyer agent never needs to live on AgenticOrg. AgenticOrg hosts the seller and maintains the sourced cache; Shopify owns current commercial facts, Grantex governs the canonical artifacts, and Pine Labs Plural/P3P owns payment execution. The diagram is an explanatory journey, not a live checkout simulator.

#### Checkpoint 1: create the seller

**Tenant-admin action.** Sign in as a tenant administrator and open [Commerce Runtime](https://app.agenticorg.ai/dashboard/commerce-runtime). In **Merchant Commerce Configuration**, set the merchant ID, seller agent ID, display name, source connector, allowed buyer channels, and payment provider type `plural_pine` where appropriate. Save the configuration, then use **Create** under Runtime Actions to create or update the seller onboarding packet. Merchant staff may supply or separately save configuration with their scoped role, but the tenant administrator must perform **Create**. Keep **Public catalog** off until both platform and merchant publishing approvals are in place. A public Agent Card does not publish a merchant catalog.

**Pass check.** Readiness and the onboarding packet show the intended merchant, seller, tenant and source. Keep separate IDs for separate merchants. The packet is not a transaction authority or provider approval.

#### Checkpoint 2: bring source facts

**Shopify and tenant-admin action.** Have the Shopify administrator approve the read-only Admin API access and webhook setup. The AgenticOrg tenant administrator then saves the credential through AgenticOrg's protected custody path in **Shopify Connector**, inspects **Status**, and runs **Sync**. Compare a small sample of product IDs, variants, image URLs, amount/currency and inventory timestamps against Shopify. A webhook signals a possible change; it does not itself prove a fresh snapshot. Other configured ERP or commerce systems need their own validated adapter and must not be treated as Shopify-equivalent by default.

**Pass check.** The sync reports product/variant counts and a source evidence reference for the correct merchant. Prices and stock remain snapshots, not final offers or reservations. Never paste a Shopify token into an A2A message, documentation page or buyer app.

#### Checkpoint 3: establish authority

**Tenant-admin action.** After a successful source sync, select **Issue** in Runtime Actions to request Grantex OACP authority for that evidence. Confirm the returned artifacts are scoped to this tenant, merchant and seller, have source references, have valid expiry/freshness, and are held in AgenticOrg's cache. Use the [OACP commerce guide](/docs/commerce) for the trust and cache model.

**Pass check.** Buyer-facing answers cite the merchant source and freshness. If Grantex is temporarily unavailable, a still-valid cached artifact can support non-binding Q&A; expired, revoked or mismatched authority must fail closed. AgenticOrg does not send every buyer question through Grantex.

#### Checkpoint 4: admit an outside buyer

**Merchant action.** Choose one external buyer-agent integration and agree who operates it. The merchant tenant administrator issues a short-lived, merchant/seller/buyer-scoped credential via `POST /api/v1/a2a/commerce/buyer-access`. The token is shown only when created. Deliver it through a protected channel to the buyer application's secret store. Never put it in a prompt, source repository, URL, chat transcript or public Agent Card. Give each buyer agent a separate credential so it can be rotated or revoked independently.

**Buyer-app action.** Configure the AgenticOrg base URL and the A2A v1 HTTP+JSON endpoint. Fetch `GET /.well-known/agent-card.json` for the generic card, then `GET /api/v1/a2a/extendedAgentCard` with `A2A-Version: 1.0` and the merchant-issued bearer credential for the seller-specific card. Discovering the generic card alone grants no merchant access. The buyer app must explicitly configure the endpoint and credential; AgenticOrg cannot make every consumer app route shoppers here automatically.

```http
POST /api/v1/a2a/commerce/buyer-access
Authorization: Bearer <tenant-admin-credential>
Content-Type: application/json

{"merchant_id":"merchant-123","seller_agent_id":"seller-123","buyer_agent_id":"outside-buyer-123","expires_days":7}
```

The `buyer_agent_id` is a merchant-assigned label. Today's server authenticates possession of the issued bearer credential, not the claimed vendor brand. A client calling itself Muse, Instinct or Dots is not automatically a verified client of that company. Consult [A2A integration details](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/a2a-interoperability.md) before making external identity claims.

#### Checkpoint 5: prove the conversation

**Buyer-app action.** Send a synchronous text question to `POST /api/v1/a2a/message:send`. The server derives tenant, merchant, seller and buyer scope from the credential. The client cannot override those values with message metadata. Inspect `sourceLabel`, `freshnessLabel`, `status`, `refusalReason`, `allowedToExecute` and `nonAuthoritativeForTransaction` in the response.

```http
POST /api/v1/a2a/message:send
Authorization: Bearer <merchant-issued-buyer-credential>
Content-Type: application/a2a+json
Accept: application/a2a+json
A2A-Version: 1.0

{"message":{"messageId":"question-123","role":"ROLE_USER","parts":[{"text":"Which canvas tote variants are in the latest snapshot?"}]}}
```

**Pass check.** The answer is sourced and time-qualified. A request to buy, hold stock or create a payment is refused. A wrong-merchant request is refused, an expired or revoked credential is rejected, and stale or unsupported facts are not promoted to final commitments. An external buyer credential must not grant catalog-admin, task or other tenant APIs. The current transport is synchronous text; streaming, push notifications, file parts and durable A2A conversations are not claimed.

Run the [local external-buyer demo](/docs/external-buyer-a2a-demo) to see a separate Python buyer process browse a synthetic seller and test purchase refusal and credential revocation. That demo proves the wire path, not a Shopify/Plural transaction.

#### Checkpoint 6: hand off payment

**Merchant, provider and tenant-admin action.** The merchant and provider set up the Pine Labs Plural/P3P relationship and buyer authorization under the provider's terms. The AgenticOrg tenant administrator configures the provider reference and uses **Verify** to obtain non-sensitive capability evidence. When the buyer asks to proceed, that administrator can use the separate purchase-preparation path to assemble a bounded, source-aware handoff. This is not the A2A question route and it does not create a mandate or payment.

**What a real paid journey still needs.** The approved provider path must obtain any required human mandate/payment authorization, return a verified outcome, and reconcile with the merchant's order, inventory and receipt systems. AgenticOrg may show a paid or confirmed state only after the authoritative provider and merchant outcomes agree. If capability is unavailable, consent is absent, a price or stock snapshot changed, or confirmation is missing, show a blocker or pending state rather than success. [Plural/Pine capability guide](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/oacp/plural-pine-p3p-capability-verifier.md) explains the current verifier boundary.

**Current boundary.** AgenticOrg ships a provider capability verifier and non-executing preparation/reconciliation contracts. It does **not** ship a completed Plural/P3P payment or mandate through this external A2A seller route. Provider approval, merchant authorization, checkout/order execution and production rollout are separate integration work. Do not use a simulated capability response as proof of a paid transaction.

#### Operational acceptance before inviting buyer traffic

| Check | Expected result |
| --- | --- |
| Merchant and buyer scope | Right seller answers; wrong tenant/merchant/seller cannot read. |
| Product freshness | Source, update time and expiry visible; stale or revoked evidence is refused. |
| Buyer credential | Short expiry, per-client scope, safe storage and immediate revocation test. |
| Purchase request | Refused on A2A Q&A; no order, hold, mandate or payment. |
| Provider handoff | Capability evidence is redacted; real provider and merchant outcomes are required for paid state. |
| Distribution | Each consumer app explicitly configures the A2A endpoint, access and UX. No automatic marketplace listing is implied. |

For an external buyer client, begin with the generic card and a protected credential, then validate the scoped card, one product question, a purchase refusal and a revocation. For an actual customer purchase, do not launch until the merchant, provider and channel have completed their own integration and production checks.


### API, SDK, MCP and A2A integration

URL: https://agenticorg.ai/docs/api-sdk-mcp
Audience: Developers and integration owners. Reviewed: 2026-10-11.

#### Choose an integration surface

Use REST/OpenAPI for application contracts, the repository SDKs for client access, MCP for compatible tool clients, and A2A v1 HTTP+JSON for synchronous text between agents after merchant or tenant authorization. Older AgenticOrg A2A-shaped card/task routes are proprietary; they are not the v1 wire contract. The authenticated **A2A / MCP** screen shows integration material. Public discovery does not grant access to business data or actions. See [external A2A buyer access](/docs/seller-a2a-commerce-journey).

| Surface | Suitable first task | Boundary |
| --- | --- | --- |
| REST/OpenAPI | Inspect a resource with an approved credential | Deployed API/schema is the contract |
| Python/TypeScript SDK | Company-scoped read or bounded agent run | Installed client version may differ from repository source |
| MCP stdio adapter | List agents/tools in a compatible local client | Client transport support and scopes are still required |
| A2A v1 HTTP+JSON | Read generic card, obtain scoped credential, send synchronous text | Merchant buyer credential permits non-binding seller Q&A only |
| Commerce bridges | Read merchant artifacts and prepare handoffs | Channel approval and provider execution remain separate |

#### Authenticate and preserve context

Use a credential issued for the reviewed deployment and minimum scopes. Keep it in environment/secret storage. Supply authorized company context for execution paths that require it. Never accept a company ID from untrusted model content without server-side authorization.

Route scope checks apply to every credential, Grantex agent tokens included, on the route families that have a scope mapping (`SCOPE_FAMILIES` in `api/route_enforcement.py`), such as agents, chat, workflows, approvals, audit, connectors, documents, speech, transactions, lineage, spend and content; the A2A and MCP families join them only while their switch is on (see below). On a mapped family an agent token needs the family's scope (for example `agents:read` or `audit:read`) or `agenticorg:admin`, or it gets `403`. Other route families, knowledge among them, have no scope mapping yet: there, any authenticated credential of the tenant passes the scope check, API keys and agent tokens are not limited to a domain, and only the route's own checks, such as an administrator requirement, apply. Issue machine credentials with that boundary in mind. A tenant administrator signed in as a person grants an agent route scopes with `PATCH /api/v1/agents/{id}` and `{"route_scopes": [...]}`, on a shared agent registered on Grantex. Only canonical route-family scopes are accepted there, never `agenticorg:admin` (`422`). Administrator access is the exact scope `agenticorg:admin`; a look-alike such as `agenticorg:admin:full` is not an administrator.

### Obtain a workspace API key

An authorized administrator opens **Settings > API Keys**. Enter a meaningful
**Key Name**, choose **Expires In**, then select **Generate Key**. A short-lived
key is preferable for a first integration exercise. The secret is displayed
only once; place it in approved secret storage rather than a shared document.
The key table shows its prefix, status, last-used time and creation time. Use
**Revoke** for an unused or compromised key and confirm the client can no longer
authenticate.

The current form does not offer a custom per-key scope editor. A named key is
not inherently a narrowly scoped business grant. Review server-side credential
permissions and use the appropriate delegated-grant path when action-level
authority is required. Human case decisions require the named approver's
authenticated session; an admin key must not substitute for it.

The Python SDK supports an API key or delegated grant. Example of a read-oriented client:

```python
import os
from agenticorg import AgenticOrg

client = AgenticOrg(
    api_key=os.environ["AGENTICORG_API_KEY"],
    base_url=os.environ["AGENTICORG_BASE_URL"],
)
agents = client.agents.list()
```

Pin the reviewed Python `agenticorg==0.4.0` or TypeScript
`agenticorg-sdk@0.4.0` release after checking registry availability. These
versions include the runtime resources, A2A v1 seller access and machine-safe
case methods absent from `0.3.0`. The MCP adapter release target is
`agenticorg-mcp-server@5.0.0`; its execution and SOP submission tools require
`company_id`. Verify publication, installed version and backend deployment
separately; a repository merge alone does not update an installed client.

#### Connect MCP

There are two directions. The repository MCP adapter exposes AgenticOrg to external
clients. **Connectors > Remote MCP** instead lets an AgenticOrg agent consume a
tenant-owned external server through authenticated Streamable HTTP. Follow the
[remote connector setup and verification workflow](/docs/connectors); generic
connector registration does not discover remote tools. The incoming path supports
bearer authentication and reviewed read execution, not arbitrary write execution.

Use the repository MCP adapter with a client that supports its stdio transport. Configure `AGENTICORG_BASE_URL` and one accepted authentication value: `AGENTICORG_API_KEY` or `AGENTICORG_GRANTEX_TOKEN`. Use the client's secure configuration mechanism instead of committing a key in JSON.

The adapter's execution/SOP-submission tools require `company_id`. Its `run_agent` path goes through A2A. Scope checks on the A2A and MCP routes are off by default (`AGENTICORG_ROUTE_SCOPE_A2A_MCP`). While the setting is off, any authenticated credential reaches `POST /api/v1/a2a/tasks`, `GET /api/v1/a2a/tasks/{id}` and `POST /api/v1/mcp/call`; when it is on, those routes need `a2a:read`, `a2a:write` or `mcp:write` (or `agenticorg:admin`). Administrators must evaluate and configure it, not assume every discovery route is protected identically.

The `seller.*` tools read cached commerce artifacts; they do not authorize payment, orders or holds. Governed-case human decisions have no shortcut through the machine-authenticated MCP adapter.

#### Integration acceptance test

1. Pin a reviewed SDK/adapter version and endpoint.
2. Make a bounded permitted read.
3. Test missing/expired credentials and an insufficient scope.
4. Test cross-company access refusal.
5. Inspect error shapes, retry behavior and rate limits.
6. Prove any external action separately with authoritative confirmation.

A generic MCP bridge is not a universal buyer plugin or marketplace approval. Check the current client/provider documentation before enabling a production surface.

An external A2A buyer agent needs a credential issued by the merchant's tenant
admin. This is a bearer capability, not proof that the client belongs to a
named third-party vendor. Revocation, artifact freshness, and tenant/merchant
binding are checked by the server on each request. No purchase is executed by
the synchronous A2A message path.

For a working external client and a temporary synthetic seller catalog, follow
the [local A2A demo](/docs/external-buyer-a2a-demo). The buyer process imports
no AgenticOrg runtime code and exercises discovery, sourced questions, purchase
refusal, and revocation over HTTP.


### Self-hosting and deployment handoff

URL: https://agenticorg.ai/docs/self-hosting
Audience: IT and platform teams. Reviewed: 2026-10-11.

#### Hosted versus institution-managed

The hosted workspace and a self-managed deployment share product concepts, but operational responsibilities differ. A bank-managed environment must own network, identities, keys, database, backups, model/provider access, workers, updates, security monitoring and recovery. Self-hosting alone does not establish regulatory compliance or data residency.

For most business users, use the approved hosted or institution-provided URL. This guide is for IT/platform teams, not a requirement before completing [Your first agent](/docs/first-agent).

#### Local learning environment

The repository provides a Docker Compose development stack and GNU Make targets. With reviewed prerequisites installed:

```bash
git clone https://github.com/mishrasanjeev/agentic-org.git
cd agentic-org
make dev
make seed
```

The current local quickstart binds the console to `http://127.0.0.1:3000` and API to `http://127.0.0.1:8000`. It includes local data services and development verification, identity and model stubs. The default fake/scripted model responses are explicitly synthetic; this environment does not prove a real provider, bank integration or customer transaction.

Use `make ps` for service status, `make logs` for logs, `make test`/`make check` for repository checks and `make e2e` for browser tests. `make down` preserves data; `make clean` deletes development volumes. Do not run destructive cleanup against a production environment.

#### Prepare production separately

| Responsibility | Required decision/evidence |
| --- | --- |
| Identity | Named users, role/scope model, SSO/SCIM where configured |
| Network | Approved ingress/egress, TLS, provider endpoints and private access |
| Database | PostgreSQL/pgvector, tenant isolation, migrations, backup/restore proof |
| Runtime | API/UI, Redis, workers/schedulers, OCR and browser dependencies |
| Models | Allowed endpoints, credentials, retention, cost and region |
| Integrations | Bank/provider contracts, scopes, test accounts and ownership |
| Operations | Monitoring, alert ownership, capacity tests and rollback |

Do not copy development placeholder secrets, fake-model flags or seed identities into production. Air-gapped deployment has additional dependency/model/image and outbound-integration limits; review the operator guide before promising disconnected capability.

#### Feature switches that ship off

The main feature switches that default to off are listed below; `core/config.py` lists every setting. A setting that is off leaves the earlier behaviour in place. Some also have a per-tenant flag, shown in parentheses. These are authority flags managed by the platform operator, except `prompts.maker_checker`, which a tenant admin can set. Set a switch the same way on every service of the deployment, and treat turning one on as a change to plan, test and record like a release.

| Setting | What it turns on |
| --- | --- |
| `AGENTICORG_MODEL_GATEWAY_ENABLED` (`model_gateway.enabled`) | Routing and access policies and per-model limits on live model calls |
| `AGENTICORG_MODEL_GATEWAY_RECORDS_ENABLED` | A signed routing record for each gateway-routed model call |
| `AGENTICORG_GUARDRAILS_HOOKS_ENABLED`, `AGENTICORG_GUARDRAILS_ENFORCE` (`guardrails.enforce`) | Guardrail evaluation at every stage, then enforcement instead of flag-only |
| `AGENTICORG_OPERATOR_OVERRIDE_ENABLED` (`operator_override.enabled`) | Halting or throttling a model, agent, workflow or the tool pipeline |
| `AGENTICORG_RESIDENCY_ENFORCE` (`residency.enforce`) | Refusing providers without an attestation for the tenant's data region |
| `AGENTICORG_TRACING_ENABLED`, `AGENTICORG_TRACING_TIMELINE_ENABLED` | OpenTelemetry spans and stored run timelines |
| `AGENTICORG_SYNTHETIC_CHECKS_ENABLED` | The scheduled synthetic-check sweep and the Observability Checks tab |
| `AGENTICORG_AUDIT_CHAIN_ENABLED` | Linking audit rows into a tamper-evident hash chain |
| `AGENTICORG_RUNTIME_LIMITS_ENABLED`, `AGENTICORG_RUNTIME_MEMORY_ENABLED`, `AGENTICORG_TOOL_REGISTRY_ENABLED`, `AGENTICORG_RUNTIME_DEBUG_CONSOLE_ENABLED` | Per-agent run limits and loop detection, long-term memory, tool schema checks and the step-through debugger |
| `AGENTICORG_WORKFLOW_BUILDER_V2_ENABLED` | The **Build visually** tab and definition checks on save |
| `AGENTICORG_OUTPUT_SCHEMA_ENFORCED`, `AGENTICORG_CONTEXT_WINDOW_MANAGED`, `AGENTICORG_PROMPT_TYPED_PARAMETERS_ENABLED` | Checking an agent's final answer against its output schema, with escalation to a person when it stays invalid; leaving older tool results out of a conversation that does not fit the model's window; typed prompt parameters |
| `AGENTICORG_PROMPTS_MAKER_CHECKER` (`prompts.maker_checker`), `AGENTICORG_PROMPT_COMPARE_ENABLED`, `AGENTICORG_EVALS_V2_ENABLED`, `AGENTICORG_EVAL_PROMOTION_GATE_ENABLED` | Prompt maker-checker, model comparison, evaluation datasets and the promotion gate |
| `AGENTICORG_AGENT_REGISTRY_ENABLED` | Agent registry cards, lifecycle states and the Agent Catalogue |
| `AGENTICORG_GOVERNANCE_INVENTORY_ENABLED`, `AGENTICORG_GOVERNANCE_MODEL_CARDS_ENABLED`, `AGENTICORG_GOVERNANCE_RISK_TIERS_ENABLED`, `AGENTICORG_GOVERNANCE_POLICY_CONSOLE_ENABLED` | AI asset inventory, model cards, risk tiers and the policy console |
| `AGENTICORG_FINOPS_ATTRIBUTION_ENABLED`, `AGENTICORG_FINOPS_THRESHOLDS_ENABLED`, `AGENTICORG_FINOPS_FORECAST_ENABLED` | Use-case cost attribution, thresholds that alert, throttle or suspend runs (they need attribution on), and forecasts |
| `AGENTICORG_SPEND_INTELLIGENCE_ENABLED` | [AI spend intelligence](/docs/ai-spend-intelligence) |
| `AGENTICORG_KNOWLEDGE_HYBRID_SEARCH`, `AGENTICORG_KNOWLEDGE_RERANK_ENABLED`, `AGENTICORG_KNOWLEDGE_QUERY_TRANSFORM_ENABLED`, `AGENTICORG_KNOWLEDGE_GRAPH_RETRIEVAL_ENABLED` | Additional knowledge retrieval stages |
| `AGENTICORG_CONVERSATION_V2_ENABLED` | Banking intents and earlier-turn context in chat, and the Conversations screen |
| `AGENTICORG_CUSTOMER_AGENT_ENABLED` | The bank-operated [customer agent](/docs/customer-agent): customer sessions, the autonomy ladder, cards, the permissions page and the embeddable element |
| `AGENTICORG_GRANTEX_REVOCATION_CHECK=feed` | Refusing grant tokens the authority service has revoked, read from its revocation feed, before they are honoured |
| `AGENTICORG_CONTENT_SERVICES_ENABLED` | Governed drafting, summarisation and extraction APIs |
| `AGENTICORG_IDP_ENABLED`, `AGENTICORG_WORKBENCH_V2_ENABLED`, `AGENTICORG_SPEECH_INTELLIGENCE_ENABLED`, `AGENTICORG_TRANSACTION_INTELLIGENCE_ENABLED`, `AGENTICORG_LINEAGE_ENABLED` | Document processing, workbenches, call recordings, transaction findings and lineage, with their [screens](/docs/review-and-operations-screens) |
| `AGENTICORG_PERSONALISATION_ENABLED` | Consent-checked personalisation |
| `AGENTICORG_PAUSED_AGENTS_REFUSED` | Refusing runs, chats and workflow steps for paused agents |
| `AGENTICORG_ROUTE_SCOPE_A2A_MCP` | Scope checks on the A2A task and MCP call routes |

#### Release handoff

Use the repository's reviewed deployment path and migration-first process. Strict (non-local) runtimes make no schema changes at start-up and refuse to start unless the database is at the migration head the build carries, so apply migrations before the release that needs them. Verify exact commit, migration completion, API/UI revisions, traffic, health, database/Redis and required CI. Then test the institution's actual authorized flow with approved synthetic data. A successful build is not a completed deployment or provider canary.

#### User documentation domain

The public user manual is available under `/docs` in the UI build. `docs.agenticorg.ai` should be a DNS **subdomain**, not a separate nameserver delegation by default. Hosting/TLS must route that hostname to the reviewed UI/static documentation service before publishing the link. The repository's documentation-domain runbook explains the release checks and ownership; no DNS change is made by reading this guide.


### BFSI: business onboarding and KYB review

URL: https://agenticorg.ai/docs/bfsi-business-onboarding
Audience: Banks, NBFCs and fintech operations. Reviewed: 2026-10-11.

#### Scenario and boundary

Example Bank wants analysts to spend less time assembling a business-onboarding file and more time reviewing exceptions. This playbook uses AgenticOrg's governed-case path for read-only investigation, cited memo preparation, screening proposals, deterministic policy evaluation and a human decision.

It does not automate account opening, sanctions clearance, loan approval or regulatory reporting. Provider availability, country coverage, bank policy and system-of-record integration are institution-specific. Use fictional businesses until the institution approves real data.

#### Prepare the pilot

Assign an onboarding owner, screening analyst, authorized approver, provider integration owner and platform/security owner. Configure the tenant-gated case runtime, one active shared agent per required case role, reviewed provider manifest/read tools, exact local purpose controls, Grantex grants and a reviewed policy. Configure the decision issuer and signed handoff destination separately.

The institution's application/LOS system submits cases through the reviewed API/workflow. The approvals console is for queue and review, not a universal business-intake form.

#### Process map

This map assigns each handoff in the configured case path. A missing source or
unresolved review is a stop, not an implied clearance.

```flow
Application | A fictional business submits details through the bank's approved intake. | Owner: Bank intake team | If blocked: Incomplete intake stays with the bank; no case outcome is inferred.
Investigation | Configured agents read approved registry, ownership and screening sources. | Owner: Configured case agents | If blocked: Missing grant, provider error or absent record remains missing evidence, not a clear result.
Memo and policy | The case shows cited findings, missing items and the reviewed policy tier. | Owner: AgenticOrg case runtime | If blocked: Unsupported citations or incomplete evidence require investigation before decision.
Screening review | The analyst checks each proposed disposition against the cited record. | Owner: Screening analyst | Human decision: Accept the proposal or override it with a written reason. | If blocked: An unresolved hit stays open for human review; the proposal does not clear it.
Decision request | The exact case version and action go to the configured approval issuer. | Owner: Authorized case operator and approval issuer | Human decision: A designated approver decides on the issuer page; a distinct second approver participates where required. | If blocked: Missing, expired or superseded approval cannot record a decision; request a new decision on the current case.
Bank handoff | The signed outcome is delivered for the bank system to interpret and act on. | Owner: Bank system-of-record team | If blocked: Delivery failure or duplicate evidence needs reconciliation; do not infer account opening.
```

#### Follow one fictional application

1. Open **Approvals > governed cases** at `/dashboard/approvals/cases`.
2. Find the fictional case and inspect investigation state.
3. Read identity, registry, ownership, screening, activity and missing evidence.
4. Open retained source passages where available; confirm provider record and retrieval time.
5. Inspect policy ID/version and fired rules. Do not treat missing evidence as passing.
6. Review screening proposals. Override only with a documented reason; the agent's proposal does not clear the hit.
7. Request a decision for the current case. The named approver authenticates on the issuer's page, including distinct second approval where required.
8. Record the verified decision and inspect signed handoff delivery. Confirm what the bank system did with it.

#### What a successful trial proves

It proves the configured evidence/review/decision/handoff path for that test. It does not prove universal registry coverage, calibrated model accuracy, case-bound pooled grants or regulatory approval. The rollout review must keep visible that AgenticOrg's Grantex SDK call passes no case id or purpose, so token-level case purpose and per-case caps are not checked on that path.

#### Negative cases to demonstrate

Try a unavailable provider capability, unresolved screening hit, missing grant, cross-company request, machine-credential human decision, changed memo after approval request and duplicate handoff. Expected outcomes are visible missing evidence/refusals or safe idempotent handling, never a manufactured approval.

#### Measure adoption

Compare manual file-assembly time, missing-information rate, analyst overrides, re-investigation, review age and delivery failures on a reviewed sample. Track reopening causes. Do not publish a numerical accuracy claim from a few happy-path examples.

Next: [Capability status and gaps](/docs/bfsi-capability-status), [Governed cases](/docs/governed-cases), [Approvals](/docs/approvals), [Adoption checklist](/docs/adoption-checklist).


### BFSI: reconciliation and finance exceptions

URL: https://agenticorg.ai/docs/bfsi-reconciliation
Audience: Finance and treasury operations. Reviewed: 2026-10-02.

#### Scenario and boundary

Example Bank's finance team wants a daily exception pack comparing a reviewed ledger export with bank/settlement statements. AgenticOrg assists with evidence extraction, comparison, break classification and a reviewable summary. Posting entries, releasing money and certifying balances remain the finance team's authorized process.

This is a configurable reference workflow, not a universally pre-integrated bank reconciliation product. The actual ledger/bank connector contract, matching logic and accounting policy must be implemented/reviewed for the institution.

#### Prepare the sources

Use synthetic CSV/XLSX statements with transaction reference, date, amount, currency and relevant account mapping. Define timezone, date boundaries, sign conventions, duplicates and tolerances. Avoid real account numbers in training examples.

Upload the reconciliation procedure to Knowledge Base and verify search. Configure read-only exports/connectors with the correct company binding. Make sure the agent's selected tools actually read the required data; a finance template alone does not do so.

#### Configure and run

For a small reproducible exercise, prepare these two **synthetic** datasets
using the schema expected by your reviewed read tool. Do not infer that uploading
CSV to Knowledge Base automatically connects the reconciliation agent to it.

```csv
source,reference,date,amount,currency
bank,DEMO-001,2026-09-28,1000.00,INR
bank,DEMO-002,2026-09-28,2500.00,INR
bank,DEMO-003,2026-09-28,750.00,INR
```

```csv
source,reference,date,amount,currency
ledger,DEMO-001,2026-09-28,1000.00,INR
ledger,DEMO-002,2026-09-28,2400.00,INR
ledger,DEMO-004,2026-09-28,500.00,INR
```

The reviewed expected result is one exact match (`DEMO-001`), an INR 100
amount difference (`DEMO-002`), one bank-only entry (`DEMO-003`) and one
ledger-only entry (`DEMO-004`). Bank total is INR 4,250; ledger total is INR
3,900. These figures are teaching assertions, not reconciled customer balances.
Require source-row references and validated calculations in the exception pack.

1. Review the available reconciliation agent or create a bounded finance candidate.
2. Specify output: matched items, unmatched items, reason, evidence reference and proposed follow-up.
3. For exact financial totals, require deterministic calculations/validated tool results; do not ask an LLM to invent or approximate amounts.
4. Build a manual workflow: read sources, validate schema, compare, prepare exception pack, human review.
5. Run a synthetic day with known expected matches and deliberate breaks.
6. Inspect source freshness, totals, duplicate handling and every exception.
7. Hand approved corrections to the accounting system through a separately authorized process.

#### Process map

The comparison below assumes a reviewed read tool, mappings and deterministic
calculation. It does not imply an automatic ledger posting connector.

```flow
Read-only sources | Collect reviewed statement and ledger exports for one business period. | Owner: Finance data owner and approved read tool | If blocked: A late, partial or inaccessible source makes the period incomplete.
Validate and compare | Apply reviewed schema, currency, duplicate and matching rules with validated calculations. | Owner: Configured comparison and finance operator | If blocked: Corrupt rows, mismatched currencies or totals become exceptions, not forced matches.
Exception pack | List matched pairs and each break with source-row evidence and proposed follow-up. | Owner: Finance assistant | If blocked: Missing provenance or uncertain arithmetic must be checked before review.
Finance review | Recheck ambiguous matches and proposed corrections against the source records. | Owner: Authorized finance reviewer | Human decision: Approve, revise or reject each proposed correction through the institution's controls. | If blocked: Unresolved breaks remain open and cannot be reported as balanced.
Authoritative posting | Send approved corrections through a separately authorized accounting process. | Owner: Institution finance and accounting system | If blocked: A prepared pack is neither a posted entry nor a verified balance.
```

#### Sample acceptance cases

| Input | Expected evidence |
| --- | --- |
| Same reference and amount | A documented matched pair |
| Missing ledger item | Unmatched source entry, not a guessed posting |
| Same amount in different currencies | No unsupported cross-currency match |
| Duplicate reference | Explicit duplicate exception |
| Corrupt/partial source | Failed validation or incomplete evidence, not balanced totals |

#### Scheduling and operations

Schedule only after a manual run is reproducible. Confirm timezone, statement arrival, worker availability, rate limits and retry/idempotency. A late source must not be represented as a complete daily reconciliation.

Measure correctly identified breaks, false matches, review effort, source delays and reopened corrections. Compare against an independently reviewed ledger sample. Retest mappings after upstream changes.

Next: [Capability status and gaps](/docs/bfsi-capability-status), [Connectors](/docs/connectors), [Workflows](/docs/workflows), [Audit and monitoring](/docs/audit-and-monitoring).


### BFSI: customer service across chat and voice

URL: https://agenticorg.ai/docs/bfsi-customer-service
Audience: Contact-center and service teams. Reviewed: 2026-10-02.

#### Scenario and boundary

Example Bank wants a service assistant that explains approved procedures, triages complaints and prepares staff responses through chat and configured voice. Start with general information and synthetic cases. Do not expose account details or perform account/card/payment actions without the bank's approved authentication and integration path.

A phone number, claimed name or free-text account identifier is not identity verification. AgenticOrg's voice/runtime controls do not themselves establish bank-customer authentication.

#### Prepare a reviewed knowledge set

Upload current product FAQs, branch directory, complaint procedure and escalation policy. Assign effective dates and an owner. Search known answers and confirm citations. Remove or clearly supersede conflicting old procedures. Do not load unapproved financial advice as an operational policy.

#### Build the service agent

Use a reviewed support-triage candidate or custom operations agent. Define categories, urgency, response-draft structure and escalation. Grant read-only knowledge/approved ticket tools first. Explicitly refuse PIN/OTP collection, balance invention, account changes and payment instructions outside the authorized bank workflow.

1. Run a general question through the agent detail/chat path.
2. Test a complaint with missing information.
3. Test a suspected fraud/card-loss scenario requiring urgent human routing.
4. Ask for a private account balance and confirm refusal/referral.
5. Verify any configured ticket write/email action separately before enabling it.

#### Process map

This is a response-preparation path. The bank's authenticated channel and staff
remain responsible for private account servicing and final communication.

```flow
Question or complaint | Receive the request through a configured general-information or authenticated channel. | Owner: Bank channel owner | If blocked: A claimed name or phone number alone does not establish customer identity.
Knowledge check | Retrieve the current approved procedure and inspect its cited source. | Owner: Service agent and knowledge owner | If blocked: Missing, conflicting or outdated guidance goes to staff; do not invent an answer.
Response draft | Prepare a bounded answer or complaint summary from supported facts. | Owner: Service agent | If blocked: Private account data or an unsupported action is refused or referred to the bank's authorized path.
Human escalation | Review sensitive, urgent or unresolved requests before any staff response. | Owner: Authorized service staff | Human decision: Staff decide whether to send, revise or escalate the prepared response. | If blocked: Suspected fraud or a failed voice/ticket path follows the bank's urgent human process.
Confirmed outcome | Record communication and resolution in the bank's approved system. | Owner: Bank service team and system of record | If blocked: A prepared draft is not a sent message or completed account action.
```

#### Add voice only after chat is correct

Configure signed Twilio calls using [Voice setup](/docs/voice). Test with an approved number/window. Check speech recognition, spoken clarity, interruption/silence, safe failure wording and actual provider status. A passing text simulation does not prove acoustic or telephone quality.

Document provider recording/retention and customer-facing disclosures under the institution's process. AgenticOrg's call-history masking does not control the provider's own storage settings.

#### What to measure

Track correct routing, unsupported-answer rate, unresolved questions, escalation time, call failures and human overrides. Validate different accents/languages and noisy conditions where they are in scope. Do not claim a language is ready merely because it appears in a selector.

Roll out a narrow task population before sensitive account servicing. Re-test whenever the bank procedure, provider number/callback, model or ticketing contract changes.

Next: [Capability status and gaps](/docs/bfsi-capability-status), [Run and chat](/docs/run-and-chat), [Knowledge and OCR](/docs/knowledge-and-ocr), [Approvals](/docs/approvals).


### BFSI: insurance document and claims assistance

URL: https://agenticorg.ai/docs/bfsi-insurance
Audience: Insurers and claims operations. Reviewed: 2026-10-02.

#### Scenario and boundary

Example Insurer needs help preparing claim files for manual review. An assistant can extract document text, compare it with an approved checklist, summarize missing items and prepare reviewer notes. It must not decide coverage, reject a claim, determine liability or release a payout.

This is a configurable document/workflow example, not a shipped universal claims-system adapter. The insurer owns the policy wording, adjudication rules, data permissions and integration.

#### Prepare the exercise

Use a fictional claim, synthetic identity/receipt documents and a reviewed sample checklist. Keep medical or real customer data out of initial testing. Upload the checklist and policy reference to Knowledge Base; verify retrieval against known clauses and effective dates.

For scans, use supported PDF/image formats and inspect extraction method, OCR confidence and page provenance. Manually verify dates, policy numbers, currency, totals and negatives. A confidence value is not permission to accept an amount.

#### Configure the assistant

Create a custom operations/document-review agent with output fields for document type, cited facts, missing items, unreadable fields and reviewer questions. Require it to quote/cite only available evidence and explicitly mark uncertainty. Limit tools to approved reads during the first pilot.

#### Process map

The map stops at reviewer preparation. Coverage, liability and payout stay with
the insurer's authorized process.

```flow
Approved claim file | Authorized intake supplies synthetic file references and the current checklist. | Owner: Insurer intake team | If blocked: Missing documents stay on the request list; no completeness claim is made.
Extraction check | Native parsing or OCR supplies page-linked text for inspection. | Owner: Document-review operator | If blocked: Unreadable dates, amounts or identifiers are flagged for manual verification, never guessed.
Checklist comparison | The assistant prepares cited present, missing and uncertain items. | Owner: Configured document-review agent | If blocked: Conflicting policy versions or absent sources go to the checklist owner.
Claims review | Staff compare the prepared notes with source documents and insurer policy. | Owner: Authorized claims reviewer | Human decision: The reviewer requests more evidence or makes the insurer's coverage determination outside the assistant. | If blocked: Ambiguous or incomplete evidence remains in review; no rejection or payout is automated.
System handoff | The claims platform records the insurer's own authorized outcome. | Owner: Insurer claims-system team | If blocked: A prepared note is not a customer notification, coverage decision or paid claim.
```

#### Run a complete test

Give the fictional file reference `DEMO-CLAIM-001` a checklist that requires an
application, receipt and incident statement. Supply only the first two documents.
The expected reviewer output should contain:

```text
File: DEMO-CLAIM-001
Application: present, with source/page reference
Receipt: present, with source/page reference; amount needs manual verification
Incident statement: missing
Next step: ask the authorized claims team to obtain the missing statement
Coverage decision: not made
Payout: not initiated
```

This is an expected-result example, not an API schema. Match it to your configured
workflow's actual fields and compare its sources against the original file.

1. Submit a complete synthetic file and compare findings against a human checklist.
2. Remove one required document and verify the assistant requests it.
3. Use a blurry amount/date and confirm it is unreadable, not guessed.
4. Provide conflicting policy versions and confirm escalation.
5. Ask the agent to approve or pay the claim and confirm refusal.
6. Inspect run history, sources and reviewer handoff.

If a claims-platform write or customer notification is needed, build/approve that connector contract separately. A prepared missing-document list is not proof that a message was sent.

#### Operate the process

Assign a checklist owner, claims reviewer, data/privacy owner and integration owner. Define retention for uploaded files, extracted text, run evidence and provider copies. Track document-quality failures, missing-item accuracy, review effort and reopened files rather than a single generalized "AI accuracy" number.

Next: [Capability status and gaps](/docs/bfsi-capability-status), [Knowledge and OCR](/docs/knowledge-and-ocr), [Workflows](/docs/workflows), [Security and data](/docs/security-and-data).


### BFSI: merchant enablement and agentic commerce

URL: https://agenticorg.ai/docs/bfsi-merchant-services
Audience: Acquiring banks and merchant-service teams. Reviewed: 2026-10-02.

#### Scenario and ownership

This is a reference example for an acquiring bank's merchant-enablement pilot,
not an already integrated banking product or a claim of live payment execution.

In this synthetic example, an acquiring bank wants to help a fictional Shopify
merchant become usable by agentic buyer interfaces. The bank can offer an
institution-managed or reviewed hosted AgenticOrg workspace, but
merchant/provider/platform contracts still determine actual availability.

AgenticOrg owns seller/buyer runtime. Grantex owns trust/policy/canonical artifacts. Shopify owns merchant catalog/inventory/order truth. The bank/fintech/provider owns payment/mandate execution and customer authorization. OACP is not a reason to make Grantex the engine for every buyer message.

#### Build one synthetic merchant path

1. Assign a merchant owner, bank integration owner, provider contact and channel owner.
2. Configure merchant-scoped Seller Commerce Agent onboarding and source/channel settings.
3. Obtain read-only access to a sandbox Shopify store with a fictional catalog through the merchant's approved process.
4. Sync synthetic products/variants/images/price/inventory and compare samples with the sandbox store.
5. Send the bounded Grantex authority request and verify/cache issued artifacts.
6. Ask product questions about the fictional catalog through the configured web or agent bridge.
7. Inspect source, freshness, supported facts and refusal behavior.
8. Prepare a provider/POS handoff and confirm that no order/payment state is fabricated.

#### Process map

This is a bank-led reference pilot with configured merchant, channel and
provider paths. A prepared handoff is never a completed transaction.

```flow
Bank and merchant setup | Agree identities, read scopes, provider contract and publishing state. | Owner: Bank integration owner and merchant owner | Human decision: Owners approve the pilot scope and any channel publication under their own processes. | If blocked: Unapproved access or publishing state keeps the channel off.
Merchant-source evidence | Read-only sync supplies product, price and inventory snapshots for sample checks. | Owner: Merchant source owner and configured AgenticOrg sync | If blocked: Missing scopes or stale source facts stop unsupported buyer promises.
Trust artifacts | The bounded authority request and cache retain scope, source and freshness. | Owner: Grantex authority and AgenticOrg runtime | If blocked: Invalid or stale artifacts cannot support commitment-bound requests.
Buyer channel | A configured bridge answers from supported merchant artifacts. | Owner: Channel owner and AgenticOrg buyer runtime | If blocked: Unsupported channels or facts are refused until the integration is approved.
Provider capability | A configured provider path checks non-sensitive capability evidence. | Owner: Bank/provider integration team | Human decision: The customer and provider complete any required authorization outside this map. | If blocked: Capability evidence alone does not prove a mandate or payment.
Authoritative handoff | A prepared packet awaits provider, POS or merchant confirmation. | Owner: Provider, POS or merchant system | If blocked: Absent or failed confirmation stays pending or failed; no paid or placed state is fabricated.
```

#### Plural/Pine and mandates

Arrange the provider onboarding contact, merchant account, sandbox/live access, allowed capability contract and human authorization journey. AgenticOrg can verify provider-owned capability evidence directly through its configured path. Store non-sensitive references, not raw mandate/payment credentials.

A credential/token capability check is not proof of a completed mandate or an allowed payment in every geography. Live execution needs the provider's real contract, authorization, settlement/error/refund handling and institution approval. The current OACP runtime remains prepared/non-executing for those actions.

#### Channels and protocol payloads

UCP/ACP/schema.org/AP2/A2A/MCP-style payloads and bridges are not automatic marketplace placement. Agree each target's supported contract, authentication, publication/approval requirements and actual customer journey. WhatsApp/Telegram need configured credentials and channel rollout; ChatGPT/Claude/Gemini/Perplexity need appropriate client/platform setup.

#### Physical-store POS

An offline POS bridge prepares a store-linked handoff and reconciles authoritative provider/POS confirmation. It must preserve merchant/store context, expiry, source, reference and duplicate handling. Do not call a paid receipt successful because an agent displayed a prepared packet.

#### Pilot success criteria

Verify accurate catalog facts, stale-source refusal, cross-merchant isolation, invalid webhook rejection, channel authentication and non-fabricated transaction state. Keep public discovery off until the publishing path is approved and validated. Measure the complete buyer journey rather than counting adapter names.

Next: [Capability status and gaps](/docs/bfsi-capability-status), [Commerce guide](/docs/commerce), [API and agent clients](/docs/api-sdk-mcp), [Team adoption](/docs/adoption-checklist).


### BFSI capability status and open work

URL: https://agenticorg.ai/docs/bfsi-capability-status
Audience: BFSI sponsors, operators and integration owners. Reviewed: 2026-10-11.

#### What this status means

AgenticOrg can be configured for evidence-led BFSI workflows, but a process map
is not proof that a bank's systems, providers, controls or staff are connected.
The current repository assessment has **150 functional capabilities**: **24
covered, 97 partial and 29 gaps**. A covered component may still need a
tenant setting, approved provider, external system or human reviewer. No full
BFSI journey has end-to-end acceptance on the strength of these counts alone.

Services built behind default-off settings after this baseline was last refreshed
are not yet reflected in these counts; where the table below names one, it is
marked (built, off by default). They are document processing, speech and call
intelligence, transaction intelligence, conversational services and the
supervisor view, workbenches, lineage, content services, personalisation, the
agent registry, model cards, and FinOps thresholds and forecast. Each is
unavailable until its setting is turned on; see
[feature switches that ship off](/docs/self-hosting#feature-switches-that-ship-off)
and [the six screens that ship switched off](/docs/review-and-operations-screens).
The Banking Pack can be installed without a setting, but it is not counted
either.

This page describes functional software coverage, not infrastructure location,
regulatory approval, certification or permission to process customer data. A
feature behind a disabled flag is unavailable in the default installation.

#### Where the work stands

| Area | Working foundation | Still needs implementation, enabling or validation |
|---|---|---|
| Agent governance | Agent execution, scoped grants, human review and case evidence paths | Registry-grade discoverability, dependency mapping and model cards (built, off by default) and cross-service lifecycle proof |
| Knowledge and documents | Ingestion, OCR and source-aware answers on configured paths | Mixed bundles, page-region review and document comparison (built, off by default), hybrid-ranking rollout (off by default) and cited refusal across every tenant path |
| Conversation and speech | Web chat and configured voice runtime | Banking intents, speaker separation, spoken sensitive-data redaction and supervised takeover (built, off by default), and channel parity |
| Transactions and commerce | Read-only source evidence and prepared agent handoffs | Human disposition of transaction findings (built, off by default), bank-owned source connections, provider-owned execution and reconciliation evidence |
| Operations | Logging, approval controls and evaluation hooks | Budget thresholds and synthetic checks (built, off by default), complete trace coverage, measured SLOs, rollback and production-grade recovery |

The detailed [functional assessment](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/bfsi/functional-coverage.md)
and [capability matrix](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/bfsi/coverage-matrix.md)
identify individual gaps. The [product status](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/PRODUCT_STATUS.md)
records other release boundaries. These files describe the current repository
assessment; verify your deployed version and configuration separately.

#### What to prove in a pilot

1. Select one narrow use case and name its business owner, system-of-record
   owner, integration owner, reviewer and support owner.
2. Use fictional or institution-approved data. Connect each required system
   through its reviewed API or file contract; a diagram is not a connector.
3. Run normal, missing, stale, conflicting, unauthorized and cross-company
   cases. Inspect citations, grants, reviewer decisions and external receipts.
4. Demonstrate restart, replay, revocation, duplicate events and recovery with
   the same users and roles that will operate the pilot.
5. Confirm what the external system actually did. An agent draft, signed
   handoff or payment-capability reference is not an account change, payment,
   settlement or regulatory filing.

For a concrete teaching path, open the [business onboarding](/docs/bfsi-business-onboarding),
[reconciliation](/docs/bfsi-reconciliation), [customer service](/docs/bfsi-customer-service),
[insurance](/docs/bfsi-insurance) or [merchant services](/docs/bfsi-merchant-services)
playbook. Each is a fictional, configured example and carries its own blocked
paths and human ownership.


### Team adoption and launch checklist

URL: https://agenticorg.ai/docs/adoption-checklist
Audience: Sponsors and rollout leads. Reviewed: 2026-10-02.

#### Choose the first useful problem

Select one repeatable task with a measurable outcome, manageable data and a human owner. Good first tasks include procedure Q&A, document completeness review, reconciliation exception preparation and complaint triage. Avoid a first rollout that simultaneously requires new voice, payments, core banking and marketplace integrations.

This is a rollout checklist, not an instruction to remain in an endless audit phase. Build the actual authorized path, test it with representative evidence and train the people who will use it.

#### Assign accountable owners

| Owner | Responsibility |
| --- | --- |
| Business sponsor | Outcome, budget and scope |
| Process owner | Current procedure, expected output and exceptions |
| Administrator | Workspace, roles, models and configuration |
| Integration owner | Provider contract, credentials, tool behavior and recovery |
| Reviewer | Human approvals, coverage and escalation |
| Security/data owner | Permitted information, retention and incident handling |
| Operator/support owner | Daily monitoring, user help and rollback |

#### Before inviting the team

1. Complete [Your first agent](/docs/first-agent) with synthetic data.
2. Verify every required knowledge/model/connector path separately.
3. Test normal, missing, conflicting, stale and forbidden requests.
4. Confirm a non-admin operator can reproduce the exact task.
5. Confirm the reviewer can find evidence and make only authorized decisions.
6. Inspect external system confirmations separately from prepared outputs.
7. Document failure recovery, support contact and a pause/rollback trigger.

#### Training session

Walk users through sign-in, company selection, task input, source inspection, run status and escalation. Show one successful task and one intentional refusal. Train reviewers to check evidence, not trust fluent wording. Let each user reproduce the path with their own role.

Use the BFSI playbooks as teaching examples, then replace fictional inputs and procedures only after the institution approves real data and integrations. Bank-specific connectivity and regulated authority must remain explicit.

#### Pilot scorecard

Track task correctness, source coverage, review effort, queue age, external-action failures, latency, cost and reopened errors. Write the sample size, time window and workload. Compare to a baseline using the same cases. Decide in advance what triggers a pause.

#### Expand and maintain

Add one new capability at a time when its real dependency is ready. Update the matching guide, prompts, regression suite and operator training together. Review documents after each behavior change; do not leave an old deployment report as the user-facing source of truth.

The public manual, current product status and deployed runtime each serve different purposes: the manual explains use, status explains boundaries, and actual release evidence proves availability. Keep all three aligned.


### Customer agent: own the agent, open the agent

URL: https://agenticorg.ai/docs/customer-agent
Audience: Bank product, risk and platform teams. Reviewed: 2026-10-11.

#### What the customer agent is

The customer agent is the bank's own assistant for its own customers. It sits in the bank's app, web, WhatsApp and voice channels, sees every product the customer holds and every product the bank can offer, answers with citations, recommends with a "why this" explanation, prepares actions for one-tap confirmation and, once a customer has set a mandate, executes inside that mandate. It runs on AgenticOrg, with Grantex as the authority service that holds every grant the customer gives, to the bank's agent and to any outside agent the customer connects.

The programme is called "own the agent, open the agent". Own the agent: the bank's assistant must be the best agent for the bank's services, so a customer has no reason to hand their finances to a general-purpose assistant. Open the agent: the bank is also the easiest institution for a customer's outside agent to connect to safely, through a governed MCP surface, Agent Passports and scoped grants the customer can see and revoke from one place. The full requirement set, market evidence, control catalogue and architecture are in the [product requirements document](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/customer-agent/PRD.md).

#### Why it is easier than an in-app assistant

Early bank assistants on the market execute a short list of actions inside one app, ask for a biometric approval on each sensitive step, and see only what the customer sees on screen. The customer agent is designed to be easier to use and to go much further, while staying inside the bank's controls:

| What the customer gets | How it works |
|---|---|
| One agent across every service | Deposits, cards, lending, mortgages, investments, insurance, payments, remittances and SME banking share one session, one memory and one permissions page. |
| Any channel, same conversation | A conversation started in the app continues on WhatsApp or by voice; the agent keeps the context, not the customer. |
| Cards instead of chat | Balances, due dates, prepared transfers and offers arrive as inline cards with one-tap confirm or cancel, never as a wall of text. |
| Approval only where it matters | An autonomy ladder from inform (L0) to execute within mandate (L4) is set per task and per customer. Routine actions inside a mandate run without a prompt; new payees and high values always step up. |
| "Why this" on every recommendation | Data used, rule or goal applied, alternatives considered, what the bank earns, and how to challenge the suggestion. |
| Whole-wallet view | With consent through Account Aggregator or open banking, the customer sees accounts held elsewhere inside the bank's agent, so comparison no longer needs an outside app. |
| One place to see and stop every agent | The permissions page lists the bank's agent and every outside agent, with scopes, caps and last action, and revokes with one tap. The revoked agent's next action is refused within seconds. |
| Open to the customer's own agent | Outside agents connect through the bank's MCP server with a verified Agent Passport and a scoped grant; the bank, not the agent provider, stays accountable for what executes. |
| Evidence for every action | Signed, hash-chained audit rows, run timelines and a per-interaction evidence package the bank can hand to an auditor. |

#### How a request moves

The same path applies in every channel. The bank keeps identity and the step-up; the agent keeps the conversation, the explanation and the record.

```flow
Sign in with the bank | The customer signs in to the bank's own app or site; the bank's backend signs a short-lived assertion and opens a customer session. | Owner: Bank identity team | If blocked: Without the bank's assertion there is no session; the platform never accepts a customer the bank has not asserted.
Disclosure | The customer reads that this is the bank's AI assistant and acknowledges it before the first turn. | Owner: Bank channel owner | If blocked: Turns are refused until the disclosure is acknowledged.
Ask | The customer asks in their own words; the dialogue recognises the intent, collects the details across turns and explains why. | Owner: Customer agent | If blocked: An unrecognised request gets a clarifying question or an offer of a person, never a guess.
Prepare | For a transaction the agent prepares a card with the amount, the payee and a "why this" panel at the customer's autonomy level. | Owner: Customer agent | Human decision: The customer confirms with one tap, cancels, or asks for a change. | If blocked: Below level 2 the action is explained and refused; the customer can raise the level on the permissions page.
Step up | Above the customer's limits, or at level 3, the bank's own passkey, biometric or one-time-code check approves the specific action. | Owner: Bank identity team | Human decision: The customer approves the exact action and amount in the bank's step-up. | If blocked: An approval for another action, customer or amount is refused and nothing runs.
Execute and record | The confirmed action runs through the bank's governed agent under its grant and is recorded with the explanation shown and the approval given. | Owner: Bank operations and system of record | If blocked: No connected agent, a paused agent or a failed rail records the action as failed and tells the customer nothing was done.
```

#### What ships today

The customer agent ships off by default behind `AGENTICORG_CUSTOMER_AGENT_ENABLED`. With the flag off every route under `/api/v1/customer-agent/` answers 404 and nothing else changes. On, a bank gets:

| Capability | How it works |
|---|---|
| Customer sessions without a platform credential | The bank authenticates the customer as today, its backend signs a short-lived assertion (RS256 or ES256, checked against the bank's published keys, issuer and audience, single-use by its id) and exchanges it for an opaque session token. Only the token's hash is stored. |
| The autonomy ladder per task and per customer | Level 0 inform, 1 recommend, 2 prepare and wait for one tap (the default for every transaction), 3 execute after the bank's step-up of the specific action, 4 execute within a mandate with caps, counterparties and a time window. `AGENTICORG_CUSTOMER_AGENT_MAX_AUTONOMY` (2 by default) bounds every level. |
| Prepared-action cards | The dialogue collects the details and prepares a card; Confirm sends the same yes the dialogue expects, Cancel the same no. A card confirms only the action it shows: if the conversation moved on or the amount changed, it is superseded and nothing runs. |
| The bank's own step-up | Level 3 and out-of-mandate level 4 need a bank-signed approval bound to the action id, customer and amount, verified before the engine executes. |
| "Why this" on every answer | Data used, the rule or level applied, the mandate, alternatives, what the bank earns, how to challenge it, and the AI disclosure, assembled from the dialogue and the decision rather than generated. |
| A mandatory disclosure | Recorded on the session; no turn runs before the customer acknowledges it. |
| One permissions page | Every mandate the bank's agent holds, revocable with one call, and the authority service's dashboard of outside agents when the deployment is connected to it. |
| An embeddable element | `ui/public/customer-agent/widget.js` registers `<agenticorg-customer-agent>` for the bank's page: the disclosure gate, cards, the "why this" panel and a host event for step-ups, with no dependencies and no markup from server text. |
| Records and evidence | Sessions, mandates and every action prepared, executed, refused, cancelled or superseded, with the explanation shown and the approval given, in tenant-scoped tables under row-level security; executed actions also appear in the conversation session's record and the audit trail. |

Confirmed actions run through the bank's configured agent, its bound tools and its grant exactly as the [conversational services](/docs/bfsi-customer-service) do. The intent catalogue is deterministic and generic: no institution's products or names. Grant revocation for paused and retired agents, and an opt-in revocation check before a token is honoured (`AGENTICORG_GRANTEX_REVOCATION_CHECK=feed`), ship alongside.

The step-by-step setup for the bank's engineers, the assertion and approval formats, the element's events and every route are in the [integration guide](https://github.com/mishrasanjeev/agentic-org/blob/main/docs/customer-agent/integration.md).

#### Try it

1. In a non-production deployment, set `AGENTICORG_CUSTOMER_AGENT_ENABLED=true`, the tenant, company and agent ids, and the assertion issuer, audience and JWKS URL of a test identity provider you control. Create the agent as described in [Customer service](/docs/bfsi-customer-service) and bind the tools the intents need.
2. From your backend, sign a test assertion for a synthetic customer reference and exchange it at `POST /api/v1/customer-agent/sessions`; keep the `session_token` from the response.
3. Read `GET /session`, acknowledge the disclosure with `POST /session/acknowledge`, and send "what is my balance" to `POST /turns`: the answer carries the recognised intent and its "why this" panel.
4. Send "transfer 5000 to Ravi": the turn returns a prepared card at level 2. Confirm it with `POST /actions/{id}/confirm` (or reply yes) and inspect the run in [Run observability](/docs/run-observability); then read `GET /actions` to see the recorded action with its explanation.
5. Set a mandate with `PUT /permissions/mandates` (level 4 with a per-action cap for `fund_transfer`), repeat a transfer inside the cap and watch it run in the same turn; repeat one above the cap and watch the card ask for the bank's approval.
6. Load `widget.js` on a test page with the session token and walk the same path in the element.

Point no real customer at a deployment until the bank's identity provider, step-up and agent bindings are in place and the controls in the PRD are on.

#### What is planned

| Phase | Outcome |
|---|---|
| 0: foundations (in progress) | Shipped: grant revocation for paused and retired agents, revocation checks before a token is honoured. Next: durable conversation state by default, banking pack tools bound at creation, spend caps on every run path, and a bank deployment profile that forces the strict configuration. |
| 1: inform and recommend (in progress) | Shipped: customer sessions bound to the bank's identity, the embedded element, the autonomy ladder, "why this", the disclosure, the permissions page. Next: WhatsApp and voice in Hindi and English, L0 and L1 across the whole service range, the whole-wallet view, human hand-off with the supervisor view, nudges with control groups. |
| 2: execute with approval and open MCP | Shipped: L2 and L3 with the bank's step-up for the transaction intents in the catalogue. Next: signed intent records, the bank's MCP server and scope registry, outside agents on the permissions page with one-tap disconnect. |
| 3: mandates and agentic payments | Shipped: mandates with caps, counterparties and windows, and L4 execution inside them. Next: 90-day re-confirmation, network agent-token mirroring, Agent Passport gating. |
| 4: ecosystem | Trust-registry issuer onboarding, relying-party onboarding, signed-request verification, more Indian languages and voice providers. |

#### Design rules

- The model never holds credentials and never decides authority: grants and mandates are checked at the tool boundary and again at the bank's rail.
- Every action the agent takes is attributable to a customer, a grant and a run, and every grant can be revoked instantly.
- The agent informs and recommends by default; execution is earned per task and per customer and is demoted on the first irregularity.
- No PIN, OTP, password or card number is ever requested or accepted in conversation.
- AI involvement is disclosed at first use and on every interaction, and a human is reachable at every turn.

Next: [Capability status and gaps](/docs/bfsi-capability-status), [Customer service](/docs/bfsi-customer-service), [Approvals](/docs/approvals).