a2a_agents/control_plane/
wire.rs

1//! The control-plane API's request and response bodies.
2//!
3//! Kept in one place because there are now **two** adapters on this contract —
4//! [`control_plane_router`](super::control_plane_router) serving it and
5//! [`ControlPlaneClient`](super::ControlPlaneClient) calling it — and a wire
6//! format defined twice is a wire format that drifts. Both sides derive their
7//! serialization from these types, so a field renamed here breaks the compile
8//! rather than the deployment.
9//!
10//! [`DeployedAgent`](super::DeployedAgent) is not here: it is the *service's*
11//! own return type, which the API passes straight through. Only the envelopes
12//! that exist because the transport is HTTP live in this module.
13
14use serde::{Deserialize, Serialize};
15
16use crate::runtime::RuntimeHealth;
17
18/// `POST /agents` body.
19///
20/// The agent's config as **raw, unexpanded** TOML: `${VAR}` references are
21/// resolved by the control plane against its own environment, subject to its
22/// allowlist, so a caller neither needs nor learns the secrets an agent runs
23/// with.
24#[derive(Debug, Clone, Serialize, Deserialize)]
25pub struct DeployRequest {
26    /// The agent config to deploy.
27    pub config_toml: String,
28}
29
30/// `GET /agents/:id` response.
31#[derive(Debug, Clone, Serialize, Deserialize)]
32pub struct AgentStatus {
33    /// The agent's id.
34    pub id: String,
35    /// Its current runtime health.
36    pub health: RuntimeHealth,
37}
38
39/// `GET /agents/:id/logs` response.
40#[derive(Debug, Clone, Serialize, Deserialize)]
41pub struct AgentLogs {
42    /// The agent's id.
43    pub id: String,
44    /// Captured output, oldest line first.
45    pub lines: Vec<String>,
46}
47
48/// `GET /agents/:id/logs` query parameters.
49#[derive(Debug, Clone, Default, Serialize, Deserialize)]
50pub struct LogsQuery {
51    /// Return only the last `tail` lines. Absent means the whole log.
52    pub tail: Option<usize>,
53}
54
55/// `GET /agents` query parameters.
56#[derive(Debug, Clone, Default, Serialize, Deserialize)]
57pub struct ListQuery {
58    /// Include stopped agents. Defaults to false, so a listing shows what is
59    /// actually running — the same choice `docker ps` makes.
60    #[serde(default)]
61    pub all: bool,
62}
63
64/// The body every failing route returns.
65///
66/// A single `error` string on purpose: the client turns it back into the text of
67/// its own error, so an operator running `a2a deploy` reads the control plane's
68/// diagnosis (which line of TOML, which env var) rather than a status code.
69#[derive(Debug, Clone, Serialize, Deserialize)]
70pub struct ApiErrorBody {
71    /// What went wrong, as the control plane described it.
72    pub error: String,
73}
a2a_agents/control_plane/wire.rs

a2a_agents/control_plane/
wire.rs
