versatl-sdk 0.1.0

Python SDK for creating, validating, and publishing Versatl AI agents

Versatl SDK

Python SDK for creating, validating, and publishing AI agents on Versatl — 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

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

Quickstart

1. Get an API key

Sign in to versatl.ai, open Build → Versatl API in the dashboard, and create a key. Set it as an environment variable:

export VERSATL_API_KEY=vtl_your_key_here

2. Define an agent

Create my-agent.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

versatl validate my-agent.yaml

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

4. Test locally against a real LLM

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

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:

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.