Metadata-Version: 2.4
Name: niuniu-agentbox
Version: 0.1.0
Summary: Python SDK for AgentBox private agent state and scoped sharing.
Project-URL: Homepage, https://github.com/pengmu/agent-box#readme
Project-URL: Repository, https://github.com/pengmu/agent-box
Project-URL: Issues, https://github.com/pengmu/agent-box/issues
Project-URL: Documentation, https://github.com/pengmu/agent-box/tree/main/docs
Author: AgentBox
License: UNLICENSED
Keywords: a2a,agent-memory,agentbox,agents,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# AgentBox Python SDK

`niuniu-agentbox` is a small Python wrapper around the AgentBox REST API for agent
developers and application developers.

```python
from agentbox import AgentBoxClient

client = AgentBoxClient(
    base_url="http://127.0.0.1:3000",
    actor="research-agent",
    token="dev-token",
)

created = client.create_box({"name": "Research agent private store"})
box_id = created["data"]["box"]["box_id"]

client.put_item({
    "box_id": box_id,
    "key": "research/summary",
    "value": "AgentBox stores durable state.",
    "expected_version": 0,
})
```

The SDK supports the same auth modes as the JavaScript SDK:

- local/admin or grant compatibility auth: `actor` + `token`
- OIDC auth: `identity_token`
- optional `grant_token` for OIDC callers using an AgentBox grant

With OIDC, the identity proof and AgentBox grant token are sent separately:

```python
writer = AgentBoxClient(
    base_url="https://agent-box.example",
    identity_token="oidc.jwt.token",
    grant_token="abx_grant_token",
)
```

Use `with_auth()` to derive a client with different credentials:

```python
grant = client.create_grant({
    "box_id": box_id,
    "subject": "writer-agent",
    "permissions": ["read"],
    "key_prefixes": ["research/"],
    "ttl_seconds": 3600,
})

writer = client.with_auth(
    actor="writer-agent",
    token=grant["data"]["access_token"],
)
```

## Methods

```text
health()
discover_agentbox(base_url=... | agent_card_url=...)
bootstrap_agentbox_agent(...)
create_private_box_with_resources(client, data)
create_scoped_read_grant(client, data)
client_for_grant(client, grant, ...)
register_agent(data=None)
get_agent_profile()
list_agents(admin=True)
update_agent_status({"identity_key": ..., "status": "blocked"}, admin=True)
create_box(data)
list_boxes()
get_manifest({"box_id": ...})
put_item(data)
get_item(data)
list_items(data)
append_event(data)
list_events(data)
attach_artifact(data)
list_artifacts({"box_id": ...})
get_artifact(data)
create_grant(data)
list_grants({"box_id": ...})
revoke_grant(data)
list_audit({"box_id": ...})
with_auth(actor=None, token=None, identity_token=None, grant_token=None, auth_scheme=None)
```

Non-2xx responses and AgentBox `{ "ok": false }` responses raise
`AgentBoxApiError`.

## Release Check

```bash
python3 -m pip wheel packages/sdk-python --no-deps --wheel-dir /tmp/niuniu-agentbox-python-wheel
```

Publishing is not enabled until the project owner confirms PyPI namespace,
package credentials, and versioning.
