Metadata-Version: 2.4
Name: unexhub-agent
Version: 0.1.1
Summary: UnexHub Agent runtime, Python starter and unex-agent-v1 protocol checker
Project-URL: Homepage, https://unexhub.ai
Project-URL: Documentation, https://unexhub.ai/agent-doc
Author: UnexHub
Maintainer: UnexHub
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agent,cli,mcp,runtime,unexhub
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.11
Requires-Dist: fastapi<1,>=0.115
Requires-Dist: httpx<1,>=0.28
Requires-Dist: jsonschema<5,>=4.23
Requires-Dist: mcp<2,>=1.30
Requires-Dist: openai<3,>=2.0
Requires-Dist: pydantic<3,>=2.11
Requires-Dist: pyyaml<7,>=6.0.2
Requires-Dist: referencing<1,>=0.36
Requires-Dist: uvicorn<1,>=0.34
Description-Content-Type: text/markdown

# UnexHub Agent Runtime

Build a chat Agent by supplying instructions, knowledge, and optional Python business logic. The official Runtime handles the `unex-agent-v1` container API, a default model/tool loop, streaming events, user questions, and cancellation. UnexHub supplies model and MCP capabilities for each authorized Run; UNH executes the local tools.

Requires Python 3.11–3.14. The package includes the CLI, starter template, dependency lock, and three examples. Developers do not need to clone the Runtime repository or build it from source.

## Create an Agent

Once the selected version is available on PyPI:

```sh
pip install unexhub-agent
unexhub-agent init my-agent
```

Or let uv manage the tool environment:

```sh
uvx --from unexhub-agent==0.1.1 unexhub-agent init my-agent
```

Initialization makes no network requests. `requirements.runtime.txt` pins the CLI's exact Runtime version; image builds resolve that version from the configured package index. Upgrading your local CLI does not alter existing projects or released images.

Before publication, or to carry the Runtime with the project, install a maintainer-provided wheel and initialize with it:

```sh
python -m pip install /path/to/unexhub_agent-0.1.1-py3-none-any.whl
unexhub-agent init my-agent \
  --runtime-wheel /path/to/unexhub_agent-0.1.1-py3-none-any.whl
```

The wheel must match the installed CLI version. It is copied into `vendor/` and referenced with a relative path. Fully disconnected builds also require a source or cache for third-party and business dependencies.

## Add your business rules

Edit `agent.yaml`, `instructions.md`, and `knowledge/`. The default `entrypoint: null` uses the official loop. To add Python logic, set `entrypoint: agent:run` and implement:

```python
from unexhub_agent import AgentContext


async def run(ctx: AgentContext) -> str:
    await ctx.emit("Starting the task", kind="run.progress")
    return await ctx.run_agent()
```

Use `--example browser-assistant`, `--example file-organizer`, or `--example monitoring` to initialize a complete example. The local wheel option can be combined with any example. Browser tools must be active in UNH; artifact publishing requires the platform artifact service.

## Build and cloud-test

```sh
cd my-agent
unexhub-agent check-config --config agent.yaml
docker build --platform linux/amd64 -t my-agent:0.1.1 .
```

The image listens on `0.0.0.0:8080` and provides `/health`. Use the existing UnexHub Mode A/B image validation, deployment, self-test, and review workflow. Configure chat or hybrid interaction, protocol `unex-agent-v1`, and the Runtime version inside the image. Connect an online UNH device signed into the same account and environment, then send the task in UNH.

The platform owns container creation, renewal, stopping, and cleanup. A test Run borrows an existing cloud self-test environment and does not destroy or extend it when the task ends. This package does not connect UNH directly to an Agent on the developer's machine. Container files are temporary; persist business data explicitly. Unknown outcomes must be reconciled rather than blindly replayed.

[UnexHub](https://unexhub.ai) · [Developer Center](https://unexhub.ai/agent-doc)

## Container egress proxies

Model, MCP, and artifact HTTP clients use HTTPX `trust_env=True`. They honor the platform-injected `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, and `NO_PROXY` settings. Keep loopback addresses in `NO_PROXY` for local health checks and fixtures. The container network policy must also allow the actual UnexHub Broker hostname. Rebuild existing Agent images with the updated pinned Runtime or a maintainer-provided wheel to apply this change.

## License

The Runtime, starter template, and examples are licensed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0). Generated projects retain Runtime license and attribution files in `vendor/`. Independent business code and third-party dependencies retain their respective licenses.
