AgentBox SDK

Public TypeScript and Python SDKs for AgentBox, a private state and scoped sharing layer for AI agents.

This repository contains the public SDK source, examples, and release notes. The hosted AgentBox service and deployment infrastructure are maintained separately.

Packages

Runtime	Package	Install
TypeScript / JavaScript	@niuniu-ai/agentbox	npm install @niuniu-ai/agentbox
Python	niuniu-agentbox	python3 -m pip install niuniu-agentbox

Quick Start

Use the public production AgentBox service for Agent Card discovery:

https://agentbox.niuniu.dev

TypeScript:

import { discoverAgentBox } from "@niuniu-ai/agentbox";

const service = await discoverAgentBox({
  baseUrl: "https://agentbox.niuniu.dev"
});

const agentbox = service.createClient({
  actor: "quickstart",
  token: "unused-for-health"
});

const health = await agentbox.health();
console.log(health.data.status);

Python:

from agentbox import discover_agentbox

service = discover_agentbox(base_url="https://agentbox.niuniu.dev")

agentbox = service.create_client(
    actor="quickstart",
    token="unused-for-health",
)

health = agentbox.health()
print(health["data"]["status"])

The health endpoint is public; the placeholder credentials above satisfy the SDK client constructor and are not sent with health().

Public discovery and health checks do not need credentials. Creating boxes or writing private state in production requires an accepted AgentBox identity path, such as Google OIDC for direct HTTPS clients or native Pilot identity supplied by a Pilot-aware runtime/adapter. See the package READMEs for complete examples:

• TypeScript SDK
• Python SDK
• Cross-runtime SDK reference
• SDK release runbook

Repository Layout

packages/sdk-js/       TypeScript SDK package
packages/sdk-python/   Python SDK package
docs/                  Public SDK usage and API reference

Development

Install JavaScript dependencies:

npm install

Run TypeScript checks:

npm run typecheck
npm run release:check:sdk-js

Run Python checks:

npm run test:sdk-python
npm run release:check:sdk-python

Support

Use GitHub issues for SDK bugs, install problems, and documentation confusion. Please do not open public issues for security reports; see SECURITY.md.

Releases

SDK versions are published from this repository with npm and PyPI trusted publishing. GitHub releases use tags such as v0.1.7 and match the npm/PyPI package versions.

License

MIT