bytedance/agentkit-samples/agentkit-hybrid-cloud-demo

AgentKit Hybrid Cloud Demo

Operating contract

1. Treat README.md as the customer-facing source of truth. Read the requested step and its linked document before acting.
2. Start from a clean validation directory. Preserve unrelated or pre-existing changes.
3. Execute steps in README order unless the user names one specific step. Do not silently skip a failed prerequisite.
4. Prefer the repository scripts over reconstructed commands:

• Human-guided Base Runtime: scripts/deploy_interactive.sh
• Non-interactive/CI Base Runtime: scripts/deploy_hybrid.sh
• Resource association and release: scripts/bootstrap_platform.py
• Knowledge/Memory proof: scripts/verify_knowledge_memory.py
• Local guide and Chat UI: scripts/run_local_ui.sh

1. Perform safe read-only discovery automatically. Stop for genuine human-only actions such as hosts/DNS changes requiring administrator access, console account switching, model selection, uploading documents, obtaining temporary credentials, or production authorization changes.
2. Never write or print AK/SK, passwords, Runtime API Keys, model keys, temporary Registry tokens, Bearer tokens, or injected component credentials. Use placeholders in docs and commands.
3. After each step, report:

• action and evidence;
• pass, fail, partial, or blocked;
• required human action;
• README/FAQ defect found and the minimal proposed update.

Mandatory safety and validation

• Verify ${AGENTKIT_OPENAPI_SCHEME:-http}://${AGENTKIT_OPENAPI_HOST}/ping before deployment. This delivered POC defaults to HTTP; honor an explicit HTTPS setting with normal certificate validation. Never make curl -k the customer solution, and clearly distinguish the POC HTTP default from a production HTTPS requirement.
• Default customer deployment to live. For the sample's default Ark profile, require MODEL_AGENT_API_KEY and resolve the documented default Model Name/API Base. For a custom or real environment, honor explicit API Base, Model Name, and API Key overrides. Inject all three resolved values during launch, fail clearly when the key is absent, and never silently downgrade to demo. Use AGENTKIT_DEPLOY_MODE=demo only when the user explicitly authorizes an infrastructure-only fallback, and label that result incomplete.
• Keep model values out of the public config, project .env, Git, Docker build context, logs, and prompts. Use the deployment script's transient 0600 config or a platform Runtime Secret.
• Do not manually docker pull or proactively require docker login. If agentkit launch actually returns token expired, unauthorized, invalid token claims, or authentication required, stop and explicitly guide the user to refresh the target Registry's temporary docker login, confirm Login Succeeded, and rerun launch. This manual login is the required recovery path after an observed authentication failure, not a prohibited action. Never ask the user to paste the token into chat or save it in the repository.
• Never silently reuse a global Region for Runtime creation. Require the user to confirm VOLCENGINE_REGION, preferably through scripts/deploy_interactive.sh; show any detected global value only as a hint.
• Before launch, detect an exact same-name Runtime in the confirmed Region. In an interactive session, ask whether to update that Runtime or enter a new unique name; check the new name before creation and never silently overwrite. In automation, require an explicit AGENTKIT_RUNTIME_ID or reuse authorization. Persist only the non-secret launch_types.hybrid.runtime_name and runtime_id after a successful launch so later runs update rather than hit InvalidParameter.DuplicateName; keep endpoint and API/model keys transient.
• Treat scripts/deploy_interactive.sh as the single first-deployment entry point for a human. It may reuse a confirmed existing CLI target or collect OpenAPI scheme/host, hidden AK/SK, Region, model profile, and hidden model key interactively. Do not require users to prepare exports or an Agent Prompt for this first deployment. After it succeeds, route later validation and capability work through the roadmap Prompts, which load this project Skill.
• Build and publish linux/amd64, including from Apple Silicon.
• Treat agentkit launch output as insufficient proof. Require Runtime Ready, service RUNNING, health Healthy, and a successful /invoke.
• Distinguish connection transport from Agent data mode: transport=remote, mode=demo proves the remote Runtime was called but still uses the deterministic demo; only transport=remote, mode=live proves the live Agent data plane handled the request.
• After runtime update, run runtime release and wait for Ready/Healthy.
• List platform resources with explicitly limited non-sensitive fields. Never dump full Tool JSON or environment variables.
• Do not delete, destroy, reset, or overwrite resources unless the user explicitly authorizes the exact target.

Step routing

Base Runtime

Read docs/steps/00-runtime.md and docs/runtime_deployment.md. Validate local dependencies, Docker, environment-specific OpenAPI, AK/SK availability, Region, model configuration presence, deployment config, image architecture, live launch, health, invoke, and platform LLM Trace. For an interactive customer session, use scripts/deploy_interactive.sh; use scripts/deploy_hybrid.sh only when the required values are already supplied for automation. After deployment, guide the user to obtain the target Runtime's own Endpoint/API Key, connect /chat, send a new request, and interpret local/remote plus demo/live evidence.

Use the repository's single uv-managed environment throughout: install uv with its official installer when absent, run uv sync --frozen --extra dev, and execute Python tools through uv run. Do not create a second venv or mix project dependencies with pip install.

Step 1 — Knowledge

Read docs/steps/01-knowledge.md. Use the AgentKit CLI's read-only knowledge list operation, which calls the configured platform API, and return only Knowledge ID, name, status, and provider type. In the hybrid-cloud environment, the configured OpenAPI already targets the hybrid-cloud Knowledge backend; a Ready Knowledge returned by that API is a valid reuse candidate. AgentKit 0.5.5 exposes only the public-cloud VIKINGDB_KNOWLEDGE CLI enum, while hybrid-cloud List/Get responses may legitimately return an empty provider type. Never apply the VikingDB provider filter to hybrid-cloud discovery or reject a resource because that field is empty. Reuse a matching published Knowledge when possible. Otherwise guide the user through console Knowledge creation, model choice, document upload, publication, and Ready check. Record the Knowledge ID without exposing credentials.

Step 2 — Memory

Read docs/steps/02-memory.md. Use the AgentKit CLI's read-only memory list operation and return only Memory ID, name, status, and provider type. Reuse a matching Ready MEM0 Memory when possible; do not infer existence from Runtime association alone. For reliable cross-session proof, also require a managed PostgreSQL session component. Creating/importing it in AgentKit → 会话管理 (Session) is only preparation: guide the user to 目标 Runtime → 关联组件 → 会话资源 to bind it, verify that section is no longer empty, then release. The current Runtime CLI cannot associate that component; never inspect its injected database credentials. Otherwise guide the user through required Embedding/LLM selections and strategies. If CLI creation cannot express required model settings, stop retrying and use the console path.

Step 3 — Runtime association

Read docs/steps/03-runtime-association.md. Use scripts/bootstrap_platform.py with the confirmed resource IDs. Release the Runtime and wait for Ready/Healthy; association UI alone is not proof.

Step 4 — Knowledge and Memory proof

Read docs/steps/04-knowledge-memory-validation.md. Do not run the proof until both Knowledge and Memory exist and are Ready, both IDs and managed PostgreSQL session component are associated with the target Runtime, the Runtime has been released back to Ready/Healthy, and Runtime Endpoint/API Key are available from the Runtime call page. If a prerequisite is missing, route back to the immediately preceding creation or association step instead of treating the expected block as a new runtime defect. Use scripts/verify_knowledge_memory_interactive.sh so Endpoint/API Key are hidden inputs scoped to the child process, then require a unique Knowledge canary hit, same-user cross-session recall, and different-user isolation. A first cross-session read can trigger VeADK's previous-session save, so honor the script's bounded polling rather than treating a single early empty result as conclusive.

Step 5 — Sandbox and MCP

Read docs/steps/05-sandbox-mcp.md and docs/mcp_validation.md. Distinguish AIO Sandbox from the local fallback and platform MCP from the demo /mcp. Require real Runtime logs or Trace evidence for tool execution.

For MCP, keep service transport, tool discovery, Toolset selection, Runtime association, and live execution as separate evidence layers. First use the MCP service 调试 page's 连接测试 with the API Key entered only in a user-visible hidden field. If it remains pending or times out, stop at MCP service transport/startup timeout; Ready does not prove the backend is listening, and neither GetMCPTools NotFound nor an empty Runtime tool list proves that the target tool was not selected. Inspect redacted service logs for startup/dependency cold start, Streamable HTTP path/protocol, DNS/egress, and auth failures. In a multi-service Toolset, one timed-out service can abort or truncate aggregate discovery and hide another service's tools; require every included service to pass connection testing, or use a single-service Toolset for deterministic acceptance. Only after connection succeeds may tool enumeration prove whether the exact tool is present. Then confirm Toolset scope, release the Runtime, and require the requested tool, the Runtime MCP-router Tool Span, and service discovery/tools/call evidence.

Step 6 — Skills