Milestone 4.A.3 — Agent Management APICopy Anchor Link

Status: Done Goal: Track A — Management API Server Phase: 4 — Operator Platform & Multi-Provider Estimated effort: 2 days Track: Track A — Management API Server

Why This Milestone ExistsCopy Anchor Link

The original agent management spec was already complete and correct: 8 endpoints, slug uniqueness per org (409 on conflict), cannot hard-delete an agent with total_sessions > 0. No redesign is needed here — this is one of the few pieces of the original Phase 3 plan that was production-ready as written.

One addition is needed beyond the original: default_provider and default_model (nullable fields) on AgentResponse, since Track C's per-agent model routing needs somewhere to store the default.

Non-GoalsCopy Anchor Link

• Model routing logic itself (Track C)
• Rate-limit configuration per agent (Track B)
• Agent memory stats (read-only views — covered by memories router)

Orientation (indicative)Copy Anchor Link

Named paths, package layouts, libraries, schemas, env vars, and commands anywhere on this page are rough sketches for orientation — inspiration and a baseline, not a required change list.

During implementation, expect to:

• open the live tree and follow existing patterns before inventing new ones
• research current constraints (latency, tenancy, deploy shape, libraries) more deeply than this page can
• advance the design beyond the sketch where measurement or code reality says so
• land work in different filenames, merged packages, deferred docs, or new surfaces when the situation calls for it

Prefer outcomes over matching any particular file tree or command sequence.

Areas that may be involved (situational — not a checklist):

• Management API
• Auth service
• Database schema / migrations

Suggested naming (provisional)Copy Anchor Link

Rename freely to match the change that actually lands.

• Branch: feature/m4-a-3-agent-management
• PR title: feat(api): agent management API with default provider/model fields (m4.A.3)

Endpoints (illustrative)Copy Anchor Link

Route shapes below are a planning sketch — names, nesting, and payloads may change during implementation.

GET /v1/agents → CursorPage[AgentResponse] (org-scoped)
POST /v1/agents → AgentResponse (201)
GET /v1/agents/{agent_id} → AgentResponse
PATCH /v1/agents/{agent_id} → AgentResponse
DELETE /v1/agents/{agent_id} → 204 soft-delete (blocked with 409 AGENT_HAS_SESSIONS if sessions exist)
POST /v1/agents/{agent_id}/activate → AgentResponse (status: active)
POST /v1/agents/{agent_id}/pause → AgentResponse (status: paused)
POST /v1/agents/{agent_id}/archive → AgentResponse (status: archived)

AgentResponse SchemaCopy Anchor Link

class AgentResponse(BaseModel):
 id: UUID
 org_id: UUID
 slug: str # unique per org, URL-safe, immutable after creation
 name: str
 status: Literal["active", "paused", "suspended", "archived"]
 default_provider: str | None # soft-validated (non-empty + max length); null = platform default
 default_model: str | None # soft-validated (non-empty + max length); null = org/platform default
 active_directive_version_id: UUID | None
 total_sessions: int
 created_at: datetime
 updated_at: datetime

Business RulesCopy Anchor Link

• Slug is immutable after creation (changing it would break external integrations that reference agents by slug).
• slug uniqueness enforced at DB level (UNIQUE (org_id, slug)); API returns 409 AGENT_SLUG_CONFLICT on collision.
• Soft-delete (deleted_at) succeeds only when total_sessions == 0 and no live session rows exist; otherwise returns 409 AGENT_HAS_SESSIONS. Use archive instead.
• default_provider / default_model use soft API validation only (non-empty + max length when set). Registered-provider allowlist is deferred to Track C discovery — unknown names are not rejected here.
• Pausing an agent propagates to the proxy: paused agents return AGENT_SUSPENDED on subsequent requests (ValidateAgent is uncached; ≤5s product SLA).

Success signalsCopy Anchor Link

Outcome-oriented signals that the milestone is in good shape. Exact filenames, package layouts, and commands may differ from any sketches above.

• All 8 endpoints functional with correct status codes
• Slug conflict returns 409 AGENT_SLUG_CONFLICT
• Soft-delete of agent with sessions returns 409 AGENT_HAS_SESSIONS
• default_provider / default_model fields persisted and returned correctly (null when not set)
• TestAPI_ISO_AGENT_*: org A cannot read/modify org B's agents (all return 404)
• Agent pause propagated to proxy within 5s (integration test)

PrerequisitesCopy Anchor Link

• M4.A.1 skeleton merged