Python SDK
Call the REST API from Python with a typed function for every route and operation, sync or async, generated from the API's OpenAPI specification.
vertical-ai is the REST API as typed Python
functions. It is generated from the API's OpenAPI specification, so every route
and every operation has a module, and every body and answer is a typed model.
pip install vertical-aiIt needs Python 3.10 or later. The package imports as vertical_ai.
Authenticate
Create a personal access token under Settings > API tokens, with the access your code needs: View only to read, Edit to change agents and run tests. Keep it in an environment variable, never in the code.
import os
from vertical_ai import AuthenticatedClient
client = AuthenticatedClient(
base_url="https://app.verticalai.com.au/api/v1",
token=os.environ["VAI_TOKEN"],
)The first call
from vertical_ai.api.agents import list_agents
from vertical_ai.models.problem import Problem
agents = list_agents.sync("acme", client=client)
if isinstance(agents, Problem):
raise SystemExit(f"{agents.code}: {agents.detail}")
for agent in agents.data:
print(agent.agent, agent.name, "published" if agent.published else "draft only")Each route and operation is a module under vertical_ai.api, grouped by the
API reference's sections, named after its operation:
GET /workspaces/{workspace}/agents is vertical_ai.api.agents.list_agents.
Each module has four functions:
| Function | Answers |
|---|---|
sync | The parsed answer, or a Problem |
sync_detailed | A Response with status_code, headers and parsed |
asyncio, asyncio_detailed | The same, to await |
Path parameters come first, in order; everything else is a keyword argument.
A body is a model from vertical_ai.models. An operation without its own route
is under vertical_ai.api.operations and takes the agent in its body:
from vertical_ai.api.operations import set_greeting_message
from vertical_ai.models.set_greeting_message_body import SetGreetingMessageBody
set_greeting_message.sync(
client=client,
body=SetGreetingMessageBody(
agent="acme/front-desk",
greeting_message="Thanks for calling Acme Plumbing, this is Sam.",
),
)A change lands on the agent's draft. When the latest version is published,
open a draft first with vertical_ai.api.versions.create_draft.
Errors
An error answers a Problem, the API's
problem details: code, detail, status,
and errors, estimate or retry_after_seconds when they apply. Branch on
code, which is stable, and show detail to a person. A change that deletes
something, publishes, changes live calls at once or spends credit answers
confirmation_required until you send confirm=True:
from vertical_ai.api.versions import publish_version
from vertical_ai.models.publish_version_body import PublishVersionBody
first = publish_version.sync("acme", "front-desk", client=client, body=PublishVersionBody())
if isinstance(first, Problem) and first.code == "confirmation_required":
print(first.detail)
publish_version.sync("acme", "front-desk", client=client, body=PublishVersionBody(confirm=True))Send confirm=True only once the person responsible has agreed. A test run's
refusal carries its cost in estimate.
Pages
A list answers data, has_more and next_cursor. Pass next_cursor back as
cursor, with the same filters, until it is None:
from vertical_ai.api.calls import list_calls
from vertical_ai.types import UNSET
cursor = UNSET
while True:
page = list_calls.sync("acme", "front-desk", client=client, limit=50, cursor=cursor)
if isinstance(page, Problem):
raise SystemExit(f"{page.code}: {page.detail}")
for call in page.data:
print(call.session_id)
if not page.next_cursor:
break
cursor = page.next_cursorRetry safely
Give a POST an idempotency_key so a retry after a timeout cannot run it
twice. The API answers a repeat of the same request within 24 hours with the
first answer. Retry safely has the
rules.
import uuid
from vertical_ai.api.agents import duplicate_agent
from vertical_ai.models.duplicate_agent_body import DuplicateAgentBody
key = str(uuid.uuid4())
copy = duplicate_agent.sync(
"acme",
"front-desk",
client=client,
body=DuplicateAgentBody(name="Front desk (after hours)"),
idempotency_key=key,
)Keep the key with the job, and send the same key when you retry it.
Rate limits
Each token may make 600 requests a minute. sync_detailed returns the headers,
and headers["RateLimit"] says how many are left. Over the limit, the Problem
has the code rate_limited, and retry_after_seconds says how long to wait.
Related
TypeScript SDK
Call the REST API from TypeScript or JavaScript with a typed function for every route and operation, generated from the API's OpenAPI specification.
The vai CLI
Log in from the browser, keep an agent's config in a repo, push edits to the draft, rerun its tests on every save, and gate CI on the same verdicts the app shows.