agenticorg

AgenticOrg Python SDK

AgenticOrg is owned by Orchestrum Technologies LLP. Inventor / Owner: Sanjeev Kumar. Contact sanjeev@orchestrum.in or mishra.sanjeev@gmail.com. See Ownership and contact.

Repository client for selected AgenticOrg HTTP APIs. Method availability and response shape depend on the installed SDK version, configured endpoint, authentication, tenant/company access, grants, and backend deployment. Examples below are integration candidates, not evidence of production availability or a successful provider action.

Version 0.4.0 adds runtime resources, A2A v1 seller access and client.cases. These methods are not available in 0.3.0. Confirm that the reviewed release exists in your package registry before installing it; publication is separate from a repository merge. Matching backend routes, migrations and authorization are still required.

Install

When the package is available from the configured Python package registry:

pip install agenticorg==0.4.0

Pin and review the package version used by your application.

Authentication

Create a client with an API key or delegated grant accepted by the configured endpoint:

from agenticorg import AgenticOrg

client = AgenticOrg(
    api_key="your-key",
    base_url="https://your-reviewed-endpoint.example",
)

Credentials identify a caller; they do not replace tenant/company authorization or tool grants. Keep secrets outside source control.

A delegated grant (grantex_token=) is checked against each route's scope exactly as an API key is: the grant must carry, for example, agents:read to list agents or agents:write (or its alias agents:run) to start a run by agent id. A grant with only tool scopes is refused with 403.

A2A and MCP calls are scope-checked only when the deployment sets AGENTICORG_ROUTE_SCOPE_A2A_MCP=true for the legacy routes. The new A2A v1 send_message route always requires a2a:write (or admin) for generic agent runs. A merchant-issued buyer token is limited to non-binding seller questions and does not grant generic agent execution. Then an API key or grant needs:

API keys created with the default scopes carry mcp:call, so client.mcp.call keeps working, but not a2a:write, so a run by agent type gets 403 until the key is replaced. client.a2a and client.mcp.tools read public discovery routes and need no scope. The new extended_agent_card is private.

A2A v1 seller access (0.4.0)

The tenant admin issues a one-time buyer credential, then hands it to the approved buyer agent using a protected channel. An external agent can run on any platform that sends A2A v1 HTTP+JSON; vendor-specific client enrollment is separate. These SDK methods require the matching server migration and ingress release; they are not included in the 0.3.0 wheel.

from agenticorg import AgenticOrg

admin = AgenticOrg(api_key="tenant-admin-key", base_url="https://your-reviewed-endpoint.example")
approval = admin.a2a.create_buyer_access(
    merchant_id="merchant-123", seller_agent_id="seller-123",
    buyer_agent_id="external-buyer-123", expires_days=7,
)
# Deliver approval["token"] securely. It is returned only once.
buyer = AgenticOrg(api_key=approval["token"], base_url="https://your-reviewed-endpoint.example")
card = buyer.a2a.extended_agent_card()
reply = buyer.a2a.send_message("Is the canvas tote available?")
admin.a2a.revoke_buyer_access(approval["id"])

standard_agent_card() is public; send_message(text, agent_type=..., company_id=...) runs a non-commerce agent only with a tenant credential and explicit a2a:write. See the A2A guide.

Company-scoped shadow candidate

Use an explicit company identifier when creating or generating a candidate. Keep the initial state in shadow until separately reviewed and promoted:

company_id = "00000000-0000-0000-0000-000000000001"

candidate = client.agents.create(
    company_id=company_id,
    name="Invoice review candidate",
    agent_type="invoice_review_candidate",
    domain="finance",
    authorized_tools=[],
    initial_status="shadow",
)

result = client.agents.run(
    candidate["agent_id"],
    action="review_draft",
    inputs={"document_ref": "sample-document"},
    company_id=company_id,  # required when running by agent type
)

print(result.status)
print(result.output)

The direct run uses the stored agent record; the backend must still verify its tenant and company ownership. Do not use a company identifier supplied by untrusted content without an authorized mapping.

SOP draft workflow

SOP parsing produces a draft, not an approved or launchable agent:

draft = client.sop.parse_text(
    "Receive a document, validate required fields, and route exceptions for review.",
    domain_hint="finance",
)

reviewed_config = dict(draft["config"])
reviewed_config["company_id"] = company_id
reviewed_config["initial_status"] = "shadow"

candidate = client.sop.deploy(reviewed_config)
print(candidate["initial_status"])

Before submission, review instructions, data sources, tools, grants, evidence, approval rules, and the target company. Submission does not authorize promotion or external actions.

Discovery resources

Runtime examples

types = client.knowledge.supported_types()
document = client.knowledge.upload("scanned-invoice.pdf")

products = client.commerce.products(merchant_id="merchant-123")
answer = client.commerce.ask({
    "merchant_id": "merchant-123",
    "question": "Which variants are fresh and in stock?",
})

voice = client.voice.status()
# Runtime health and call history are agent-scoped.
runtime = client.voice.runtime_health("00000000-0000-0000-0000-000000000001")
rpa_catalog = client.rpa.scripts()

place_outbound_call, rpa.run, bridges.route, Shopify sync, and provider verification are intentionally explicit methods. Call them only with reviewed tenant authorization and real external-action intent.

Inspect actual responses and errors instead of relying on illustrative output. Authorization denials should remain denials; do not automatically broaden credentials, scopes, or company context.

Governed cases

Source clients can submit an application for review and start a read-only investigation. Supply the purpose explicitly rather than relying on the API default:

case = client.cases.submit(
    {"legal_name": "Example Ltd", "jurisdiction": "GB"},
    purpose="aml.cdd.onboarding",
)
scheduled = client.cases.investigate(case["case_ref"])
record = client.cases.get(case["case_ref"])

The backend validates the tenant flag, actor, role registration, local purpose allowlist, and delegated tool grant. A 202 response means investigation was scheduled, not that it succeeded; inspect the later case state and failure reason. This SDK intentionally has no decision, withdrawal, screening-review, or information-request approval helper: those actions require a signed-in human, which an API key or agent token does not represent. MCP discovery does not expose the governed-case roles as agent tools. The legacy grantex==0.5.1 does not enforce purpose in the token or per-case caps. See case lifecycle and the tested client contract.

CLI

If the installed distribution provides the CLI, inspect commands with:

agenticorg --help

CLI behavior follows the same endpoint, evidence, authentication, and company boundaries as the Python client.

License

Apache-2.0