75 lines
4.1 KiB
Markdown
75 lines
4.1 KiB
Markdown
## Why
|
|
|
|
Today every Host Agent must hold its own LLM provider credentials
|
|
(`ANTHROPIC_API_KEY`/`OPENAI_API_KEY`) and provider/model configuration
|
|
locally, because `runtime/ai_planner.py`'s `AIPlanner` builds an
|
|
Anthropic/OpenAI SDK client directly inside the Host Agent process
|
|
(`runtime/tool_calling_client.py`). With the Host Agent now defaulting AI
|
|
planning to on, this means every edge deployment must independently
|
|
provision, rotate, and secure a provider secret. Centralizing provider
|
|
configuration and credentials in the Cloud Control Plane -- which already
|
|
authenticates every Host Agent for heartbeat/claim/lease/result traffic --
|
|
removes per-edge secret sprawl and gives operators one place to change
|
|
provider/model or rotate a key without touching any Host.
|
|
|
|
## What Changes
|
|
|
|
- Add a new Cloud Control Plane internal endpoint that accepts an AI
|
|
Planner tool-calling decision request (system prompt, user prompt,
|
|
optional screenshot, tool specs, timeout) from an authenticated Host
|
|
Agent, calls the configured LLM provider using cloud-held credentials,
|
|
and returns the resulting single tool-call decision.
|
|
- Cloud API owns `AI_PLANNER_PROVIDER`/`AI_PLANNER_MODEL`/provider API keys
|
|
as its own configuration; these are no longer required on the Host Agent
|
|
when the new proxy transport is used.
|
|
- Host Agent gains a transport setting (cloud-proxy vs. direct-to-provider)
|
|
and a new `ToolCallingClient` implementation that calls the cloud endpoint
|
|
instead of constructing a local Anthropic/OpenAI SDK client. Cloud-proxy is
|
|
the default; the existing direct-to-provider transport remains fully
|
|
supported as an explicit opt-out for hosts with local provider keys.
|
|
- Reuse the existing Host-scoped bearer credential (already used for
|
|
heartbeat/claim/renew/result) for the new endpoint; no new auth scope.
|
|
- Cloud API does not durably persist screenshot bytes or full prompt text
|
|
from proxy requests beyond the lifetime of handling the request.
|
|
|
|
## Capabilities
|
|
|
|
### New Capabilities
|
|
- `cloud-planner-proxy`: Cloud Control Plane internal endpoint and
|
|
configuration that proxies AI Planner LLM tool-calling decisions on
|
|
behalf of authenticated Host Agents, holding provider selection and
|
|
credentials centrally instead of on each edge host.
|
|
|
|
### Modified Capabilities
|
|
- `agent-runtime` (capability defined by the not-yet-archived
|
|
`ai-planner-runtime` change; this delta is written against that pending
|
|
spec, matching the precedent set by `edge-host-self-enrollment` against
|
|
the pending `edge-host-enrollment` spec): the "Pluggable dual-provider
|
|
tool-calling abstraction" requirement is extended so the tool-calling
|
|
client is selectable by transport (direct-to-provider vs. cloud-proxy) as
|
|
well as by provider identity, and provider credentials become optional on
|
|
the Host Agent when the cloud-proxy transport is selected.
|
|
|
|
## Impact
|
|
|
|
- `packages/cloud-platform/cloud` / `apps/cloud-api`: new internal API
|
|
route + request/response models, new provider/credential configuration.
|
|
No new package dependency: `device-cloud-platform` already depends
|
|
unconditionally on `device-agent-runtime` (which declares `anthropic`/
|
|
`openai`), so both SDKs are already present wherever the Cloud API runs --
|
|
confirmed by `uv run python -c "import anthropic, openai"` succeeding in
|
|
the workspace venv without any pyproject change.
|
|
- `apps/device-host-agent`: a new `ToolCallingClient` implementation
|
|
(`host_agent/cloud_planner_client.py::CloudProxyToolCallingClient`,
|
|
constructed in the `host_agent` package, not `runtime`, to preserve the
|
|
existing hexagonal boundary that forbids `runtime` from importing `cloud`
|
|
or `host_agent`) with its own synchronous `httpx.Client` (matching
|
|
`HostAgentEnrollmentClient`'s pattern, since `ToolCallingClient.decide()`
|
|
runs synchronously off the main event loop), and a new transport
|
|
configuration setting (`AI_PLANNER_TRANSPORT`).
|
|
- `runtime/tool_calling_client.py`: no changes to the `ToolCallingClient`
|
|
Protocol itself; the new implementation satisfies it structurally from
|
|
outside the `runtime` package.
|
|
- Docs: `docs/CLOUD_DEPLOYMENT.md` Runtime AI Planner section gains the
|
|
proxy-transport configuration path and its trade-offs.
|