Metadata-Version: 2.4
Name: hai-agents
Version: 0.1.6
Summary: Python SDK for H Company's Agent API: autonomous agents powered by Holo.
Project-URL: Homepage, https://hcompany.ai
Project-URL: Repository, https://github.com/hcompai/hai-agents-python
Project-URL: Issues, https://github.com/hcompai/hai-agents-python/issues
Project-URL: Documentation, https://hub.hcompany.ai/agent-api
Author-email: H Company <contact@hcompany.ai>
License: MIT
License-File: LICENSE
Keywords: agent,agents,browser-use,computer-use,h-company,llm,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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 :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<0.29.0,>=0.23.0
Requires-Dist: pydantic<3,>=2.0
Requires-Dist: typing-extensions>=4.6
Provides-Extra: all
Requires-Dist: python-dotenv<2,>=1.2.2; extra == 'all'
Requires-Dist: rich<15,>=13; extra == 'all'
Requires-Dist: typer<1,>=0.12; extra == 'all'
Provides-Extra: cli
Requires-Dist: python-dotenv<2,>=1.2.2; extra == 'cli'
Requires-Dist: rich<15,>=13; extra == 'cli'
Requires-Dist: typer<1,>=0.12; extra == 'cli'
Description-Content-Type: text/markdown

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://github.com/hcompai/hai-agents-python/blob/main/assets/banner-dark.gif?raw=true" />
    <img src="https://github.com/hcompai/hai-agents-python/blob/main/assets/banner-light.gif?raw=true" alt="H Agent API" width="700" />
  </picture>
</p>

<p align="center">
  <a href="https://pypi.org/project/hai-agents/"><img src="https://img.shields.io/pypi/v/hai-agents.svg" alt="PyPI" /></a>
  <a href="https://pypi.org/project/hai-agents/"><img src="https://img.shields.io/pypi/pyversions/hai-agents.svg" alt="Python versions" /></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
</p>

<p align="center">
  Python SDK for the <a href="https://hcompany.ai">H Company</a> <a href="https://hub.hcompany.ai/agent-api">Agent API</a>. Launch autonomous agents powered by Holo, stream their progress, and steer them mid-run.
</p>

<p align="center">
  <b><a href="https://hub.hcompany.ai/agent-api">Documentation</a></b>
  &nbsp;·&nbsp;
  <a href="https://portal.hcompany.ai">Get an API key</a>
  &nbsp;·&nbsp;
  <a href="https://pypi.org/project/hai-agents/">PyPI</a>
  &nbsp;·&nbsp;
  <a href="https://github.com/hcompai/hai-agents-ts">TypeScript SDK</a>
  &nbsp;·&nbsp;
  <a href="https://hcompany.ai">H Company</a>
</p>

## Installation

```bash
pip install hai-agents
```

Install the optional command-line entry point when you want local tools:

```bash
pip install "hai-agents[cli]"
```

Requires Python 3.10 or newer. Grab an API key at [portal.hcompany.ai](https://portal.hcompany.ai) and export it:

```bash
export H_API_KEY=hk-...
```

## Quickstart

Launch the built-in `h/web-surfer-holo3-1-35b` agent, which ships with its own browser, and describe the task in plain language. `run_session` polls until the agent finishes and returns the final answer.

```python
from hai_agents import Client, run_session

client = Client()  # reads H_API_KEY from the environment

result = run_session(
    client,
    agent="h/web-surfer-holo3-1-35b",
    messages="What are the top 3 stories on Hacker News right now?",
)

print(result.status)  # "completed"
print(result.answer)
```

An `AsyncClient` mirrors this API for asyncio.

## CLI

The `hai-agents[cli]` extra installs the `hai` command:

```bash
hai login                  # browser sign-in; stores a key in ~/.config/hai/.env
hai run "Summarize the H Agent API quickstart"
hai --json run "Reply with exactly: hello" --max-steps 3 --max-time 60
hai sessions list
hai sessions get <session-id>
hai sessions send <session-id> "continue"
hai sessions cancel <session-id>
hai sessions share <session-id>
hai mcp install            # wire the hai-agents MCP server into every detected editor
hai mcp install list       # see supported clients (Cursor, VS Code, Claude Code, Windsurf)
```

`hai mcp install` adds the remote `hai-agents` MCP server to your local editors and
writes your API key into each client config (in plaintext, so keep them private). On
clients that support agent skills (Cursor, Claude Code) it also symlinks a `SKILL.md`
that teaches the model how to drive the server.

`hai login` opens your browser, mints a per-machine API key, and writes it to
`~/.config/hai/.env`. `hai whoami` shows the resolved endpoint and whether you are
authenticated; `hai logout` removes the stored key.

Credentials resolve from flags, then `HAI_API_KEY`/`H_API_KEY` in the environment,
then a local `.env`, then `~/.config/hai/.env`. Use `--base-url` or `HAI_API_BASE_URL`
to target a specific Agent Platform host.

## Documentation

Guides, core concepts, and the full API reference live at **[hub.hcompany.ai/agent-api](https://hub.hcompany.ai/agent-api)**, covering streaming progress, steering a live session, regions, structured output, and error handling.

## License

[MIT](LICENSE)
