agent-canvas-environment

Agent Canvas Environment

Use this skill when running inside or alongside a local Agent Canvas stack, especially when the user asks to inspect the local backend, create or monitor local conversations, or delegate work to another local conversation.

Core rules

• Treat the local Agent Canvas backend as an agent-server API, usually http://localhost:8001.
• Treat the local UI as a separate frontend, usually http://localhost:8000.
• Do not print session API keys. Pass them directly in X-Session-API-Key.
• Trust any runtime-services block or explicit user-provided host over default ports.
• Before mutating a repository, check git status -sb. If a worktree has unrelated changes, use a separate worktree or clone.
• When delegating, write a self-contained prompt. The new conversation does not inherit the current chat context.

Find the session key

Use the first available value, without echoing it:

KEY="${SESSION_API_KEY:-${OH_SESSION_API_KEYS_0:-${LOCAL_BACKEND_API_KEY:-}}}"
if [ -z "$KEY" ] && [ -f "$HOME/.openhands/agent-canvas/api-key.txt" ]; then
  KEY="$(tr -d '\n' < "$HOME/.openhands/agent-canvas/api-key.txt")"
fi
test -n "$KEY" || { echo "No Agent Canvas session API key found" >&2; exit 1; }

Validate backend access:

curl -sS -o /tmp/agent-canvas-conversations.json -w '%{http_code}\n' \
  -H "X-Session-API-Key: $KEY" \
  http://localhost:8001/api/conversations/search

HTTP 200 means the backend and key work.

Delegate to a local conversation

Use POST /api/conversations with:

• the encrypted agent_settings from GET /api/settings (with X-Expose-Secrets: encrypted), which carries the real Fernet-encrypted llm.api_key, the existing agent_context, and the agent kind — so you never handle plaintext credentials and you don't drop the caller's skill/context config
• secrets_encrypted: true so the agent-server decrypts that api_key server-side
• the exec tool set merged into agent_settings.tools (and task_tool_set when you enable sub-agents)
• tool_module_qualnames for any non-SDK tools (e.g. canvas_ui)
• agent_context.load_public_skills/load_user_skills/load_project_skills set to true if the delegated agent should inherit bundled/user/project skills
• a fresh absolute workspace directory
• initial_message.run: true
• worktree: false when the workspace is already isolated