AgenticOrg

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. The platform is source-available under the Orchestrum Personal Use License 1.0: only individuals' personal use is free, and any organisation needs a signed agreement with Orchestrum Technologies LLP; the SDKs and MCP server are Apache-2.0 open source (see Licence).

Ownership: AgenticOrg is owned by Orchestrum Technologies LLP.

Inventor / Owner: Sanjeev Kumar

Contact: sanjeev@orchestrum.in | 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 and NOTICE.

Website | Application | Playground | User manual | Technical documentation | Current product status | Security policy

Start with a measurable pilot: bank service cases, fintech/API integrations, or merchant and external-buyer workflows. The visual rollout checklist explains source setup, review, external confirmation and expansion. Discuss your task and systems at sanjeev@orchestrum.in; do not send credentials or customer data in a public enquiry.

Licence

The AgenticOrg platform is source-available under the Orchestrum Personal Use License 1.0. Only an individual using it for their own personal purposes is free. Every organisation (companies, firms, sole proprietors' businesses, charities, schools, universities, research bodies and government) needs prior written permission in a signed agreement with Orchestrum Technologies LLP, for any use: evaluation, testing, pilots, internal use, hosting, resale or embedding, paid or free.

The AgenticOrg SDKs (sdk/, sdk-ts/) and the MCP server (mcp-server/) are open source under the Apache License 2.0, free for any use including commercial.

Directory	Licence
sdk/ (Python SDK)	Apache License 2.0: open source, free for any use including commercial
sdk-ts/ (TypeScript SDK)	Apache License 2.0: open source, free for any use including commercial
mcp-server/ (MCP server)	Apache License 2.0: open source, free for any use including commercial
tests/fixtures/ucp/, core/commerce/acp/schemas/ (vendored protocol schemas)	Apache License 2.0 (third-party, unchanged)
Everything else: the AgenticOrg platform (api/, core/, auth/, connectors/, ui/ and the website, workers, docs/, scripts/, migrations/, tests)	Orchestrum Personal Use License 1.0: individuals' personal use only; any organisation needs a signed agreement with Orchestrum Technologies LLP

• Free (platform): an individual's own personal use only. Distributing the platform needs a written agreement too.
• Commercial licence: see COMMERCIAL-LICENSE.md and write to sanjeev@orchestrum.in.
• Existing users: these terms apply to every version published on or after 21 October 2026, including all updates. Versions published before that date remain available under the Apache License 2.0 they were released with. Existing and new users alike need a signed agreement for any use by or for an organisation of a version from 21 October 2026 onward.
• Trademarks: "AgenticOrg" and "Grantex" are trademarks of Orchestrum Technologies LLP; commercial use of the names, logos, hosted services or brand needs prior written approval with any version. See TRADEMARKS.md.

Source of truth

Live product totals and the deployed product version are published by the public product facts endpoint:

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.

Billing limits and list prices come from core/billing/catalog.py. Production deployment behavior comes from 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. For this model, Agent Configuration > Gemini thinking offers an optional medium profile for multi-step reasoning. Existing agents and generic calls keep the provider default; no global flag or default is changed. The API equivalent is llm.thinking_level="medium"; set it to null to restore the provider default. Both runtime clients honor explicit profiles. Thinking is billed as output tokens; budget for its additional token use and response time within existing limits. It is not a correctness guarantee. Older model settings and all feature flags remain unchanged. See reasoning acceptance.

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 default to optional status notices. Telegram agent connections can opt into bounded final-answer replies for the linked private sender under Channels > Reply content. Traces and tool-call records stay in AgenticOrg; approvals, sender authorization and tenant controls still apply. The encrypted intake carries the authenticated sender identity across services; older receipts without that proof remain withheld, even if the agent completed. For tool-free Telegram agents without traffic splits in this opt-in mode, follow-ups may use up to four recent, confirmed question/answer pairs from the same linked private sender and agent/company scope, within 30 minutes. This is bounded text context, not durable memory or permission to repeat actions. Hindi and other Unicode model input remains readable before privacy scanning; existing redaction still applies. With AGENTICORG_PII_HINDI_GRAMMAR_ENABLED=true (default off), targeted Hindi grammar checks distinguish referential name/colour questions from named values. This is not a general-purpose Hindi entity-recognition model; quoted names, unknown words and structured identifiers retain privacy scanning.

Follow the channel account and workflow guide for account creation, callback registration, sender linking and verification. Local wire-contract tests are not proof of real provider-account delivery. Reuse an existing Telegram connection for an already connected bot; a second connection must not overwrite its webhook. Change its destination through Save settings only when authorized and no tasks are queued or running. Verify real model reasoning separately from transport-only workflows, and do not claim a combined Telegram-to-Gemini flow unless one delivery proves both.

Acceptance checks validate the actual answer as well as the terminal status. A completed, high-confidence model run can still be wrong; compare numeric results independently and preserve PII protections while diagnosing it. See the bounded production acceptance runbook.

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 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, grant-enforcement runbook, and decision requests.

Voice, email, OCR, and browser RPA can be exercised together before release with the Docker-backed local multichannel simulation. It uses fresh PostgreSQL, local Mailpit delivery, real Tesseract, and optional real Playwright Chromium while keeping paid calls and production mutations off.

Knowledge upload status distinguishes extraction from searchable indexing. With opt-in upload recovery, transient native embedding failures retry on the existing worker; the previous searchable copy remains until replacement succeeds. Malformed PDF/Office files are refused before replacement. See Knowledge and OCR for status meanings, citations and recovery limits. For a reasoning-only agent, disable suggested tools and leave tool/connector selection empty; this does not bypass tenant budgets. Provider charges and quotas still apply. Use structured output for confidence, keep review thresholds intact, and include explanation calls and provider retries in any test spending allowance. See Create agents and Run and chat for bounded acceptance steps and the opt-in direct-run explanation history.

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 explains the boundary. The scale and resilience assessment tracks remaining connection-scale, load, and restore work; the recovery guide 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%.

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

Loading

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, the feature reference and the rollout runbook.

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, prepared provider or POS handoffs, and flag-gated UCP and ACP surfaces (ACP feed, checkout sessions and order events)
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 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.
• The production voice path uses signed Twilio webhooks with provider-managed STT/TTS and encrypted transcript storage. See Voice runtime.
• 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.
• The public evaluation page 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.
• Outbound notifications and local-model profiles require their supporting services.
• The UCP business profile (/.well-known/ucp, UCP 2026-04-08 and 2026-08-25) with catalog search and lookup and store locations is off by default (AGENTICORG_UCP_PROFILE_ENABLED). It serves a merchant only on a DNS-attested serving host, with a per-merchant ES256 signing key, after the merchant opts in and Grantex issues an enabled public_discovery_state artifact. See UCP business profile.
• UCP checkout sessions, carts and orders (/ucp/checkout-sessions, /ucp/carts, /ucp/orders, AGENTICORG_UCP_CHECKOUT_ENABLED) are off by default. With the flag on, a Complete needs an allow decision of the commerce arbiter for the exact session and a registered executor. The Plural executor (capture, refunds, UPI AutoPay with RBI AFA) is registered only with PLURAL_PINE_LIVE_EXECUTION_ENABLED=true; otherwise Complete answers executor_unavailable. Server-verified Intent, Cart and Payment mandates from Grantex need AGENTICORG_GRANTEX_MANDATES_ENABLED. See UCP checkout, cart and order, Plural executor and mandates.
• The ACP product feed (AGENTICORG_ACP_FEED_ENABLED) and ACP checkout sessions (AGENTICORG_ACP_CHECKOUT_ENABLED, API version 2026-04-17) are off by default. The feed is built only from verified, fresh OACP artifacts; sessions run on the UCP session table, arbiter and executor and need the merchant's opt-in, a Grantex delegate-payment allowance and a registered executor (the Plural executor, off by default). See ACP product feed and checkout sessions.
• Agent request signatures (RFC 9421, Visa Trusted Agent Protocol and Web Bot Auth profiles) are verified on the public commerce reads and the A2A routes in log mode by default (AGENTICORG_HTTPSIG_VERIFY_MODE=enforce refuses unsigned requests on the commerce API surfaces: the catalog and product JSON and the A2A routes, never the public pages); the buyer connector signs its requests with the tenant agent key only with AGENTICORG_HTTPSIG_SIGN_OUTBOUND. The library (grantex-agent-httpsig 0.2.0, not on PyPI) is installed from a commit-pinned git reference to the Grantex repository, so installs need git. See agent request signing.
• 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.
• 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 table and the guide to the default-off screens.
• 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.
• No request field approves commerce execution. Execution consumes a single-use allow decision of the deterministic commerce arbiter, and the only payment executor (Plural) is off by default.
• 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 owns trust authority, protocol and policy governance, canonical artifacts and their signing keys, and adapter authority. AgenticOrg verifies every Grantex artifact before caching it. 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. Each issued OACP artifact is verified before it is cached: its ES256 detached JWS against the Grantex JWKS pinned in configuration, its scope and TTL, and its Token Status List entry. In strict runtimes one failure refuses the whole issuance (AGENTICORG_OACP_VERIFY_STRICT, on by default there); elsewhere the failure is logged as an irregularity and the artifact is cached without a verifier reference. Strict verification needs the Grantex environment to sign artifacts this way, publish an oacp- key and serve its status list; Grantex production does all three as of 2026-10-20. See docs/oacp/artifact-cache-guide.md.
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. A deterministic commerce arbiter decides each handoff (mandate, consent, Commerce Passport cap, verified fresh artifacts, merchant limits) and seals allow or refuse; it never waits for a person. Execution consumes a single-use allow decision_id bound to the exact handoff payload. Every commerce write leaves an HMAC-signed ledger row in audit_log, hash-chained once audit-chain sealing is on for the tenant (AGENTICORG_AUDIT_CHAIN_DEFAULT_ON, off by default). Until server-verified mandates exist, strict runtimes refuse caller-asserted buyer authority (AGENTICORG_ARBITER_REQUIRE_VERIFIED_AUTHORITY), and an allow is consumable only once Grantex has countersigned it (AGENTICORG_ARBITER_REQUIRE_GRANTEX_GRANT). Tenant admins read the ledger, annotate decisions, store review manifests and retention dispositions under /api/v1/commerce/runtime/ledger, and scripts/verify_ledger.py verifies a ledger export offline. See docs/oacp/arbiter-ledger.md.
8. Agent platforms can use the merchant's UCP business profile, UCP checkout and ACP checkout sessions on a DNS-attested serving host, each behind its own flag (default off). They share one session table, the same arbiter session_complete decision and the same executor.
9. Only a verified provider or merchant callback can confirm the external outcome.

Agents that call the public commerce reads and the A2A routes may sign their requests under the Visa Trusted Agent Protocol or Web Bot Auth profiles of RFC 9421; AgenticOrg verifies them, records the verified agent identity (on the commerce ledger for writes), and with AGENTICORG_HTTPSIG_VERIFY_MODE=enforce refuses unsigned ones on the commerce API surfaces (the public HTML pages, sitemap and llms.txt stay public). See docs/oacp/agent-request-signing.md.

As of 2026-10-20 all of this is on main, and the AgenticOrg production deployment of it is next; check the deployed commit before relying on it. Start with docs/oacp/README.md and the runtime launch closure PRD.

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 and 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]"
python -m pip install --no-deps --require-hashes -r requirements-fastembed.txt

The second command installs fastembed, the local embedding runtime, without its dependency metadata; requirements-fastembed.txt explains why.

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 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 /.well-known/ucp, POST /ucp/catalog/search, /ucp/catalog/lookup, /ucp/locations/*	UCP business profile, catalog and locations on a merchant's verified serving host (off by default)	Public, host-bound
POST /ucp/checkout-sessions, GET/PUT /ucp/checkout-sessions/{id}, /complete, /cancel; /ucp/carts; GET /ucp/orders/{id}	UCP checkout, cart and order on a merchant's verified serving host (off by default)	Tenant API key issued to the agent platform (ucp:read / ucp:write)
POST /acp/checkout_sessions, GET/POST /acp/checkout_sessions/{id}, /complete, /cancel	ACP checkout sessions on a merchant's verified serving host (off by default)	Tenant API key issued to the agent platform (acp:read / acp:write)
GET /api/v1/a2a/extendedAgentCard	Merchant-specific seller card	Merchant-issued buyer credential; the agent's RFC 9421 signature is verified (logged, or required in enforce mode)
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; the agent's RFC 9421 signature is verified (logged, or required in enforce mode)
GET /api/v1/public/commerce/sellers/{merchant_id}/...	Public buyer-safe seller page, catalog, product, schema.org, sitemap and llms.txt (merchant opt-in)	Public; the agent's RFC 9421 signature is verified (logged, or required in enforce mode)
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, and narrative API documentation is in 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 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.

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.

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.

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.

Pricing and limits

The hosted plan source of truth is the typed PUBLIC_PLAN_CATALOG in 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
Free	$0/month	INR 0/month	3	1,000/month	1 GB
Pro	$99/month	INR 9,999/month	15	10,000/month	50 GB
Enterprise	$499/month	INR 49,999/month	Unlimited	Unlimited	Unlimited

The platform is licensed under the Orchestrum Personal Use License 1.0; self-hosting by or for any organisation needs a signed agreement with Orchestrum Technologies LLP (see Licence). Infrastructure, model-provider, external API, payment-provider, and support costs are separate from the software licence.

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; do not open a public issue for a suspected vulnerability.

Testing

For a complete local Docker replay, use make dev, make check, make test, make seed, make seed-cases, then AGENTICORG_E2E_REQUIRE_GOVERNED_CASES=true make e2e. The tools image uses Python 3.14 like the runtime; both browser runners must match the locked Playwright version. See the local quickstart for isolated test databases, synthetic provider fixtures and decision-grant browser checks.

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 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 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
• sitemap.xml
• llms.txt
• 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. 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. The UI serves this same Markdown content at agenticorg.ai/docs, with full-text search, visual process flows, print-friendly guides and mobile navigation. The docs.agenticorg.ai alias has configured Cloud DNS and managed HTTPS; its hosting and verification instructions live in the documentation runbook.
• Functional BFSI coverage and open gaps shows what is implemented, partial or unavailable, with verification scenarios and product boundaries.
• Public BFSI capability status gives readers a plain-language summary of the same assessment, including unfinished work.
• Documents, conversations, calls and workbenches covers the console screens of services that ship off by default and the setting each needs.
• Documentation site publishing and subdomain runbook
• Marketing enquiry delivery, SMTP setup and protected model spend also covers the default-off Grantex contact-form handoff, without sales-agent execution.
• Documentation home
• Current product status
• Architecture
• API reference
• Deployment
• AI spend intelligence user guide, feature reference and rollout and enablement runbook
• Knowledge ingestion and OCR
• Local voice, email, RPA, and OCR simulation
• Voice runtime
• RPA runtime
• OACP runtime documentation
• External A2A buyer and seller access
• Local synthetic seller and independent A2A buyer demo
• Guided merchant-to-external-buyer A2A commerce journey
• Production smoke runbook
• Testing guide
• Python SDK
• TypeScript SDK
• MCP server
• Changelog
• Roadmap

The documentation home 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 and 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 and trademarks

Platform: Orchestrum Personal Use License 1.0 (LICENSE). Only an individual's personal use is free; any organisation needs a signed agreement with Orchestrum Technologies LLP (COMMERCIAL-LICENSE.md, sanjeev@orchestrum.in). SDKs (sdk/, sdk-ts/) and MCP server (mcp-server/): Apache License 2.0, free for any use. Trademarks: TRADEMARKS.md. Overview, change date and third-party material: LICENSING.md and the Licence section above.