Quickstart

Install AgentKit CLI, configure cloud credentials, create a project, and deploy an agent that you can call from the terminal. A runtime is the cloud service that hosts your agent application This tutorial follows the public commands in AgentKit CLI 0.54.0. Terminal examples use Bash or zsh

Prerequisites

A Volcengine or BytePlus account with access to AgentKit and permission to create runtimes and related build resources in the target region
An available model name, model API address, and API key for that platform
Access to the cloud console or your organization’s SSO address when using browser login

Cloud management credentials create and manage resources. The model API key authorizes model calls made by the agent

Install and check the version

The installer downloads a standalone binary without requiring Node.js. Choose a download tool available on your computer:

curl
wget

curl -fsSL https://agentkit-cli.tos-cn-beijing.volces.com/install.sh | sh

wget -qO- https://agentkit-cli.tos-cn-beijing.volces.com/install.sh | sh

The installer updates your shell startup configuration to make agentkit and its alias ak available. Follow its instructions to reload the configuration or open a new terminal, then check the version and help:

agentkit --version
agentkit --help

Continue when the terminal displays a version number and command list. See Installation options on this page for installation paths and handling of existing Python commands

Configure cloud credentials

Choose a method for your target cloud platform. Replace the placeholders and run environment variable commands in the same terminal you will use for deployment:

Volcengine access keys
BytePlus access keys
Console login
Organization SSO

export VOLCENGINE_ACCESS_KEY="your-access-key"
export VOLCENGINE_SECRET_KEY="your-secret-key"
export VOLCENGINE_REGION="cn-beijing"

export BYTEPLUS_ACCESS_KEY="your-access-key"
export BYTEPLUS_SECRET_KEY="your-secret-key"

After creating the project, explicitly select BytePlus and its region as shown below

For a Volcengine account, run:

agentkit --provider volcengine login --console
agentkit --provider volcengine whoami

For a BytePlus account, run:

agentkit --provider byteplus login --console
agentkit --provider byteplus whoami

After browser authorization, whoami should display the identity for the selected cloud platform. On a remote server, use login --remote and follow the instructions to authorize on another device

agentkit login <sso-address>
agentkit whoami

This path must obtain short-lived STS credentials that can manage cloud resources. Do not add --identity-only for this tutorial: it stores only an identity session and cannot authorize the deployment steps

Valid access keys in the environment take precedence over cached login credentials. Login does not replace them. Sign in again when SSO credentials expire. See Authentication for cloud selection and credential precedence

Create and configure a project

Create the project directory

Run these commands in the parent directory where you want to store the project. --directory sets the output location; the project name alone does not create a subdirectory:

agentkit init my-agent --template basic --directory my-agent
cd my-agent

The current directory should contain my-agent.py, requirements.txt, agentkit.yaml, and .dockerignore. Run the remaining configuration, deployment, and invocation commands from this directory

Select the cloud platform and model

Choose the platform matching your credentials. Replace the model name and API key with values available to your account:

Volcengine
BytePlus

agentkit config --launch_type cloud --cloud_provider volcengine --region cn-beijing
export MODEL_AGENT_NAME="your-ark-model-name"
export MODEL_AGENT_API_BASE="https://ark.cn-beijing.volces.com/api/v3/"
export MODEL_AGENT_API_KEY="your-ark-api-key"

agentkit config --launch_type cloud --cloud_provider byteplus --region ap-southeast-1
export MODEL_AGENT_NAME="your-modelark-model-name"
export MODEL_AGENT_API_BASE="https://ark.ap-southeast.bytepluses.com/api/v3"
export MODEL_AGENT_API_KEY="your-modelark-api-key"

agentkit config updates agentkit.yaml in the project root. This tutorial uses cloud build and deployment. See the config command for more settings

Pass model settings to the runtime

The following command writes the current environment variable values, including the real model API key, to agentkit.yaml. Before running it, add agentkit.yaml and .env to both .gitignore and .dockerignore to keep credentials out of version control and the image. Create either ignore file if it does not exist

agentkit config \
  --runtime_envs "MODEL_AGENT_NAME=$MODEL_AGENT_NAME" \
  --runtime_envs "MODEL_AGENT_API_BASE=$MODEL_AGENT_API_BASE" \
  --runtime_envs "MODEL_AGENT_API_KEY=$MODEL_AGENT_API_KEY" \
  --runtime_envs "MODEL_AGENT_PROVIDER=openai"

Double quotes let the shell expand variables before running the command. Exporting model credentials locally does not automatically pass them to the cloud runtime; this configuration supplies its environment variables

Deploy and invoke

agentkit launch builds an image and creates or updates the runtime and required resources in the selected cloud platform and region. These operations may incur charges. Check account permissions, region, model settings, and build resource settings first. Invoking the agent also consumes model usage

Build and deploy from the project directory:

agentkit launch

After deployment succeeds, check runtime status and send a test message:

agentkit status
agentkit invoke run "hello"

status shows the state of the current project’s runtime. Receiving an agent response confirms that the deployed application can handle a call. If the build or deployment fails, resolve the reported issue before invoking it. Creating local project files does not mean that cloud deployment succeeded

Installation options

The binary installs to AGENTKIT_HOME (~/.agentkit by default), with compatibility links for agentkit and ak in AGENTKIT_BIN_DIR (~/.local/bin by default). When overriding these directories, use absolute paths and keep them separate. The install directory also contains required runtime assets such as templates/, lifecycle-templates/, harness/, skills/, im-proxies/, and vendor/; when manually moving or extracting a standalone release, keep these directories beside ak in the same install directory. To install a specific version, set the AGENTKIT_VERSION environment variable (defaults to latest). If the current terminal still cannot find the command, reopen the terminal or source the shell configuration printed by the installer.

The install script writes managed agentkit and ak dispatch entries into the zsh, bash, or fish startup configuration so the standalone CLI takes priority over Python commands with the same name from pip, pipx, venv, or Conda after the shell reloads. If the current environment already has a Python agentkit command, the installer preserves it and writes a restorable shim; the uninstall script restores that entry when it is still managed by the installer. Set AGENTKIT_NO_MODIFY_PATH=1 to skip automatic shell configuration changes and print the block to add manually.

The installer retrieves the latest standalone release. Use agentkit upgrade to update an existing installation. This documentation covers the 0.54.0 release

Getting Started

AI-Friendly

Command reference

Prerequisites

Install and check the version

Configure cloud credentials

Create and configure a project

Deploy and invoke

Installation options

​Prerequisites

​Install and check the version

​Configure cloud credentials

​Create and configure a project

​Deploy and invoke

​Installation options

Prerequisites

Install and check the version

Configure cloud credentials

Create and configure a project

Deploy and invoke

Installation options