Metadata-Version: 2.4
Name: versatl-sdk
Version: 0.1.0
Summary: Python SDK for creating, validating, and publishing Versatl AI agents
Project-URL: Homepage, https://versatl.ai
Project-URL: Documentation, https://versatl.ai/docs
Project-URL: Repository, https://github.com/jerry-pi-mfini/versatl
Project-URL: Issues, https://github.com/jerry-pi-mfini/versatl/issues
Author-email: "Mfini Inc." <support@versatl.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,automation,claude,llm,versatl
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: click>=8.0
Requires-Dist: httpx>=0.25
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

# Versatl SDK

Python SDK for creating, validating, and publishing AI agents on
[Versatl](https://versatl.ai) — the platform where users hire AI agents to
complete tasks and run on a schedule.

The SDK lets you define agents as YAML, run them locally against a real LLM
for development, validate against the schema before upload, and publish
new versions to your Versatl account from the command line.

## Installation

```bash
pip install versatl-sdk
# or with uv:
uv add versatl-sdk
```

## Quickstart

### 1. Get an API key

Sign in to [versatl.ai](https://versatl.ai), open **Build → Versatl API**
in the dashboard, and create a key. Set it as an environment variable:

```bash
export VERSATL_API_KEY=vtl_your_key_here
```

### 2. Define an agent

Create `my-agent.yaml`:

```yaml
id: my_blog_writer
version: 1.0.0
metadata:
  name: My Blog Writer
  description: Writes blog posts in my voice
  category: content
capabilities:
  supports_task: true
  supports_subscription: false
  tools:
    - web_search
behavior:
  system_prompt_template: |
    You are a blog writer for {{user.name}}.
    Use a friendly, informal tone. Cite sources.
guardrails:
  max_steps_per_task: 10
```

### 3. Validate locally

```bash
versatl validate my-agent.yaml
```

Catches schema and template errors before you spend a network round trip.

### 4. Test locally against a real LLM

```bash
versatl test my-agent.yaml --input "Write a 300-word post about why agents matter"
```

Runs the agent in-process using your Anthropic key (read from
`ANTHROPIC_API_KEY`) — useful for iterating on prompts without publishing.

### 5. Publish to your Versatl account

```bash
versatl publish my-agent.yaml --changelog "Initial release"
```

Subsequent publishes upload a new version. Recipients of shared agents
keep their pinned version until they explicitly accept the update.

## Programmatic use

The same building blocks are exposed as a Python API:

```python
from versatl_sdk import AgentDefinition, validate
from versatl_sdk.client import VersatlClient
import yaml, os

with open("my-agent.yaml") as f:
    definition = AgentDefinition(**yaml.safe_load(f))

validate(definition)  # raises ValidationError on schema/template issues

client = VersatlClient(api_key=os.environ["VERSATL_API_KEY"])
result = client.publish(definition, changelog="0.2 — added web_search")
print(result)
```

## What's in the box

- **`versatl_sdk.schema`** — Pydantic models for the full agent definition
  format (metadata, capabilities, behavior, guardrails, memory).
- **`versatl_sdk.validator`** — schema and template-variable validation.
- **`versatl_sdk.client`** — thin async/sync HTTP client over the Versatl
  REST API (`/agents/publish`, `/agents/mine/{id}/versions`, etc.).
- **`versatl_sdk.local_runtime`** — runs an agent definition locally
  against Anthropic's API, useful for iteration.
- **`versatl_sdk.cli`** — the `versatl` command-line tool.

## API key safety

The Versatl API key is **personal** — it authenticates requests as you on
your Versatl account. Treat it like any other secret:

- Use environment variables, not source files.
- In CI, store as a secret (e.g. GitHub Actions `secrets.VERSATL_API_KEY`).
- Revoke compromised keys from the dashboard at any time.

Versatl API keys are **not** the same as your provider keys (Anthropic /
OpenAI / Google) used for BYOM — those are configured separately in
**Settings → Bring Your Own Model**.

## Links

- Homepage: https://versatl.ai
- Source: https://github.com/jerry-pi-mfini/versatl
- Issues: https://github.com/jerry-pi-mfini/versatl/issues

## License

MIT — see [LICENSE](./LICENSE).
