API Keys, SDK and CLI

Everything the console does is available over the REST API at https://agntapi.agntspark.com/v1.

Two kinds of keys

Key	Looks like	Can
API key	agnt_…	Act as your account: create, deploy, scale and delete agents.
Access key	agk_…	Call one private agent's URL. Nothing else.

Keep API keys in your CI's secret store. Give apps that call an agent an access key instead; see Access Keys and Rate Limits.

Create an API key

In the console, open Settings → API Keys, enter a label and click Generate key. The key is shown once.

export AGNTSPARK_API_KEY=agnt_…

curl https://agntapi.agntspark.com/v1/agents \
  -H "Authorization: Bearer $AGNTSPARK_API_KEY"

An API key can't create further API keys; that needs a signed-in console session.

Deploy with curl

curl -X POST https://agntapi.agntspark.com/v1/agents \
  -H "Authorization: Bearer $AGNTSPARK_API_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "name": "support",
    "model": "gpt-4o",
    "api_key": "'"$OPENAI_API_KEY"'",
    "deploy": {"image": "agntspark/template-customer-support:latest"}
  }'

The response is the agent: its id, its url, and, because new agents are private, access_key, its first access key. That's the only time the key is returned. See the REST API reference for every endpoint.

Python SDK

The SDK isn't on PyPI yet. Install it from GitHub:

pip install "git+https://github.com/AgntSpark1/agntspark-sdk.git"

import os

from agntspark import Client, DeployConfig

with Client() as client:  # reads AGNTSPARK_API_KEY
    agent = client.agents.create(
        name="support",
        model="gpt-4o",
        api_key=os.environ["OPENAI_API_KEY"],
        deploy=DeployConfig(image="agntspark/template-customer-support:latest"),
    )
    access_key = agent.access_key  # store it: it's only returned here
    print(agent.url)

    reply = client.agents.invoke(agent, "How do I reset my password?", access_key=access_key)
    print(reply.output)

    # Continue the conversation
    reply = client.agents.invoke(
        agent, "I use Google sign-in", session_id=reply.session_id, access_key=access_key
    )

invoke sends only the access key to the agent's URL, never your API key.

More:

client.agents.create_access_key(agent.id, label="website")   # → .key, shown once
client.agents.list_access_keys(agent.id)
client.agents.delete_access_key(agent.id, key_id)
client.agents.update(agent.id, rate_limit_rpm=30)            # None restores the default
client.agents.update(agent.id, access="public")
client.agents.scale(agent.id, direction="up", count=1)
client.agents.logs(agent.id, limit=50)

Every method has an _async variant (create_async, invoke_async, …). Errors raise AuthenticationError (401/403), NotFoundError, RateLimitError (with retry_after) or AgntSparkError.

CLI

The SDK installs an agntspark command.

agntspark init                              # saves your API key to ~/.agntspark/config.yaml
agntspark deploy agent.yaml --wait          # prints the access key once
agntspark list --status running
agntspark invoke agt_… "Hello" --key agk_…
agntspark keys create agt_… --label website
agntspark keys list agt_…
agntspark keys revoke agt_… <key-id>
agntspark access agt_… private --rpm 30
agntspark logs agt_… --follow
agntspark scale agt_… up --count 1
agntspark delete agt_…

agent.yaml uses the same fields as POST /v1/agents:

name: support
model: gpt-4o
deploy:
  image: agntspark/template-customer-support:latest
  replicas: 1

Tip

Keep model keys out of files you commit: set api_key from your secret store when generating agent.yaml in CI, or set the key once in the console.

Configuration

The SDK and CLI read, in increasing precedence: ~/.agntspark/config.yaml, then AGNTSPARK_* environment variables, then arguments to Client(...).

Variable	Default
AGNTSPARK_API_KEY	—
AGNTSPARK_BASE_URL	https://agntapi.agntspark.com/v1
AGNTSPARK_TIMEOUT	30 seconds
AGNTSPARK_MAX_RETRIES	3