AgentKit Runtime: From Local Development to Cloud Deployment

AgentKit Runtime is a unified, managed Agent execution environment designed to provide you with a secure, efficient, and scalable serverless platform, allowing you to focus on Agent business logic rather than tedious infrastructure operations.

What Does AgentKit Runtime Solve for You?

• Heavy Operational Burden: Have you ever spent significant time on environment setup, network configuration, dependency installation, manual scaling, and troubleshooting?
• Lack of Unified Management Platform: Does creating and managing separate environments for different Agents or sessions make scheduling chaotic and maintenance difficult?
• Security and Isolation Challenges: Are you concerned about permission conflicts, data leakage, or malicious access risks in multi-user or multi-Agent scenarios?
• Missing Monitoring and Logs: Do you need to spend extra resources configuring logging systems, metrics collection, and alerting rules to monitor Agent health in real-time?

AgentKit Runtime systematically addresses all these problems by providing a serverless managed environment.

Core Advantages

1. Serverless Architecture: Simplified Operations, Optimized Costs

• Zero Infrastructure Management: No need to worry about underlying servers and complex environment configurations, achieving true "code as a service."
• Unified Runtime Platform: Efficiently run and schedule multiple Agent instances (Sessions) in the same environment, with unified access points.
• Automated Lifecycle Management: Automatically scale from zero to large-scale concurrency based on real-time traffic, enabling unattended elastic scaling.
• Pay-as-You-Go: Only incur costs when Agents are running; resources automatically scale to zero when there's no traffic, maximizing cloud cost savings.
• Built-in Monitoring and Logs: Out-of-the-box real-time monitoring and logging systems make it easy to track Agent status and quickly locate issues.

2. Enterprise-Grade Security Isolation

• Multiple Isolation Safeguards: Based on mature cloud vendor virtualization and container technologies, ensuring each Agent Runtime runs in an independent, protected environment.
• Fine-Grained Access Control: Deep integration with Identity and gateway authentication, strictly isolating session context and access permissions, effectively preventing data cross-contamination and unauthorized access risks.

3. Framework-Agnostic Quick Integration

• Broad Framework Support: Deeply integrated with veADK while compatible with mainstream Python Agent frameworks, requiring minimal adaptation for quick onboarding.
• Multi-Protocol Support: Native support for HTTP, MCP, A2A, and other communication protocols to meet diverse application scenario needs.
• One-Click Deployment: Through AgentKit SDK, you can easily achieve one-click deployment from your local IDE to the cloud Runtime.

---

Three-Step Guide: From Local Development to Cloud Deployment

This guide will walk you through the complete process from environment configuration and local development debugging to ultimately deploying your Agent to a production environment.

Prerequisites

Before starting, please ensure you have:

1. A Volcengine account with AgentKit service activated, and obtain your AccessKey & SecretKey.

   Note: Please ensure your AccessKey has AgentKitFullAccess permissions.

2. Python 3.10+ installed locally.

Step 1: Environment Configuration

We recommend using uv or python3 -m venv to manage your Python virtual environment. The following examples will use uv.

For uv installation instructions, please refer to: uv installation

1. Create and Activate Virtual Environment

mkdir agentkit-runtime-quickstart
cd agentkit-runtime-quickstart
uv venv --python 3.12.0
source .venv/bin/activate

2. Install Core Dependencies

You can specify a mirror source via the --index parameter to speed up installation.

uv add veadk-python
uv add agentkit-sdk-python

Step 2: Create and Debug Agent Locally

1. Initialize Agent Project

We strongly recommend using agentkit-cli to quickly bootstrap your project. The init command creates a well-structured Agent project with streaming support from a template.

# Use agentkit-cli to create project from template
agentkit init

This automatically generates a project structure containing simple_agent.py and requirements.txt, allowing you to start development immediately.

2. Agent Code Overview

The core code of simple_agent.py generated using the basic_stream template is shown below. It demonstrates how to wrap a veADK Agent with AgentkitSimpleApp, execute it through Runner, and return results as SSE (Server-Sent Events) streams.

# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

import json
import logging

from google.adk.agents import RunConfig
from google.adk.agents.run_config import StreamingMode
from google.genai.types import Content, Part
from veadk import Agent, Runner

from agentkit.apps import AgentkitSimpleApp
from veadk.prompts.agent_default_prompt import DEFAULT_DESCRIPTION, DEFAULT_INSTRUCTION

logger = logging.getLogger(__name__)
logger.setLevel(logging.INFO)

app = AgentkitSimpleApp()

app_name = "simple_streamable_app"

agent_name = "Agent"
description = DEFAULT_DESCRIPTION
system_prompt = DEFAULT_INSTRUCTION


tools = []

# from veadk.tools.builtin_tools.web_search import web_search
# tools.append(web_search)


agent = Agent(
    name=agent_name,
    description=description,
    instruction=system_prompt,
    tools=tools,
)
agent.model._additional_args["stream_options"] = {"include_usage": True}
runner = Runner(agent=agent, app_name=app_name)


@app.entrypoint
async def run(payload: dict, headers: dict):
    prompt = payload["prompt"]
    user_id = headers["user_id"]
    session_id = headers["session_id"]

    logger.info(
        f"Running agent with prompt: {prompt}, user_id: {user_id}, session_id: {session_id}"
    )

    session_service = runner.short_term_memory.session_service  # type: ignore

    # prevent session recreation
    session = await session_service.get_session(
        app_name=app_name, user_id=user_id, session_id=session_id
    )
    if not session:
        await session_service.create_session(
            app_name=app_name, user_id=user_id, session_id=session_id
        )

    new_message = Content(role="user", parts=[Part(text=prompt)])
    try:
        async for event in runner.run_async(
            user_id=user_id,
            session_id=session_id,
            new_message=new_message,
            run_config=RunConfig(streaming_mode=StreamingMode.SSE),
        ):
            # Format as SSE data
            sse_event = event.model_dump_json(exclude_none=True, by_alias=True)
            logger.debug("Generated event in agent run streaming: %s", sse_event)
            yield sse_event
    except Exception as e:
        logger.exception("Error in event_generator: %s", e)
        # You might want to yield an error event here
        error_data = json.dumps({"error": str(e)})
        yield error_data


@app.ping
def ping() -> str:
    return "pong!"


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=8000)

Code Highlights:

• Uses Volcengine Ark Doubao model by default and automatically handles model API Key retrieval.
• Built-in session management logic ensures multi-turn conversation continuity.
• Achieves seamless integration with AgentKit Runtime through AgentkitSimpleApp.

3. Configure Environment Variables

Before starting the Agent service, you need to configure Volcengine access credentials:

# Required: Configure your Volcengine access credentials
export VOLCENGINE_ACCESS_KEY=your_ak
export VOLCENGINE_SECRET_KEY=your_sk

Important: Please replace your_ak and your_sk with your actual credentials.

4. Start and Invoke Service Locally

Once everything is ready, run the following command to start the Agent service:

python simple_agent.py

The service will listen on http://0.0.0.0:8000. Now, open another terminal and test your Agent using curl:

curl --location 'http://localhost:8000/invoke' \
  --header 'Content-Type: application/json' \
  --header 'user_id: test' \
  --header 'session_id: local_session' \
  --data '{"prompt": "Tell me a joke!"}'

Parameter Reference:

• user_id: User identifier
• session_id: Session identifier
• prompt: User's natural language request

Sample Execution Log:

After successful invocation, the console will output detailed execution logs:

INFO:     Started server process [38120]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     127.0.0.1:60807 - "POST /invoke HTTP/1.1" 200 OK
INFO:__main__:Running agent with prompt: Tell me a joke!, user_id: test, session_id: local_session
2025-12-01 20:12:50 | DEBUG | runner.py:151 - Event output: Why
2025-12-01 20:12:50 | DEBUG | runner.py:151 - Event output:  did
2025-12-01 20:12:50 | DEBUG | runner.py:151 - Event output:  the
2025-12-01 20:12:50 | DEBUG | runner.py:151 - Event output:  AI
2025-12-01 20:12:50 | DEBUG | runner.py:151 - Event output:  apply
2025-12-01 20:12:50 | DEBUG | runner.py:151 - Event output:  for
2025-12-01 20:12:50 | DEBUG | runner.py:151 - Event output:  a
2025-12-01 20:12:50 | DEBUG | runner.py:151 - Event output:  job
2025-12-01 20:12:50 | DEBUG | runner.py:151 - Event output:  at
2025-12-01 20:12:50 | DEBUG | runner.py:151 - Event output:  the
2025-12-01 20:12:51 | DEBUG | runner.py:151 - Event output:  bakery
2025-12-01 20:12:51 | DEBUG | runner.py:151 - Event output: ?
2025-12-01 20:12:51 | DEBUG | runner.py:151 - Event output: Because
2025-12-01 20:12:51 | DEBUG | runner.py:151 - Event output:  it
2025-12-01 20:12:51 | DEBUG | runner.py:151 - Event output:  wanted
2025-12-01 20:12:51 | DEBUG | runner.py:151 - Event output:  to
2025-12-01 20:12:51 | DEBUG | runner.py:151 - Event output:  work
2025-12-01 20:12:51 | DEBUG | runner.py:151 - Event output:  on
2025-12-01 20:12:51 | DEBUG | runner.py:151 - Event output:  its
2025-12-01 20:12:51 | DEBUG | runner.py:151 - Event output:  **
2025-12-01 20:12:51 | DEBUG | runner.py:151 - Event output: d
2025-12-01 20:12:51 | DEBUG | runner.py:151 - Event output: ough
2025-12-01 20:12:51 | DEBUG | runner.py:151 - Event output: **
2025-12-01 20:12:51 | DEBUG | runner.py:151 - Event output:  processing
2025-12-01 20:12:51 | DEBUG | runner.py:151 - Event output:  skills
2025-12-01 20:12:51 | DEBUG | runner.py:151 - Event output: !
2025-12-01 20:12:51 | DEBUG | runner.py:151 - Event output:  😄
2025-12-01 20:12:51 | DEBUG | runner.py:151 - Event output: Why did the AI apply for a job at the bakery?

Because it wanted to work on its **dough** processing skills! 😄

Step 3: Deploy to Production Environment

After completing local development and testing, you can deploy your agent to the AgentKit platform:

1. Package Code: Ensure all dependencies are correctly configured in requirements.txt. The code generated using the template already includes all necessary dependencies.
2. Platform Deployment: Following the Quick Start guide, use the agentkit config and agentkit launch commands to configure and deploy your application.
3. Invoke Application: After deployment, you can invoke your agent through the platform's API or SDK. Example invocation:

   agentkit invoke "Tell me a joke!"

You have now successfully completed the entire process from local development to cloud deployment!