  # backend/src/schemas/agent.py
  # #region Schemas.Agent [C:1] [TYPE Module] [SEMANTICS agent,schema,api]
  # @BRIEF Pydantic schemas for agent conversation API. Must match frontend/src/types/agent.ts exactly.
  
> from datetime import datetime
  
> from pydantic import BaseModel, Field
  
  
  # #region Schemas.Agent.ConversationItem [C:1] [TYPE Class] [SEMANTICS agent,schema,conversation]
  # @ingroup Schemas
> class ConversationItem(BaseModel):
>     id: str
>     title: str
>     updated_at: datetime
>     message_count: int
  # #endregion Schemas.Agent.ConversationItem
  
  
  # #region Schemas.Agent.ConversationListResponse [C:1] [TYPE Class] [SEMANTICS agent,schema,conversation]
  # @ingroup Schemas
> class ConversationListResponse(BaseModel):
>     items: list[ConversationItem]
>     has_next: bool = False
>     active_total: int = 0
>     archived_total: int = 0
  # #endregion Schemas.Agent.ConversationListResponse
  
  
  # #region Schemas.Agent.ToolCall [C:1] [TYPE Class] [SEMANTICS agent,schema,tool-call]
  # @ingroup Schemas
> class ToolCall(BaseModel):
>     tool: str
>     input: dict = Field(default_factory=dict)
>     output: dict | None = None
>     error: str | None = None
>     status: str = "executing"  # executing | completed | failed
  # #endregion Schemas.Agent.ToolCall
  
  
  # #region Schemas.Agent.AttachmentMeta [C:1] [TYPE Class] [SEMANTICS agent,schema,attachment]
  # @ingroup Schemas
> class AttachmentMeta(BaseModel):
>     name: str
>     type: str  # pdf | xlsx | json | csv | txt | png | jpeg
>     size: int
>     preview_url: str | None = None
  # #endregion Schemas.Agent.AttachmentMeta
  
  
  # #region Schemas.Agent.MessageItem [C:1] [TYPE Class] [SEMANTICS agent,schema,message]
  # @ingroup Schemas
> class MessageItem(BaseModel):
>     id: str
>     conversation_id: str
>     role: str  # user | assistant | tool | system
>     text: str | None = None
>     state: str | None = None
>     tool_calls: list[ToolCall] | None = None
>     attachments: list[AttachmentMeta] | None = None
>     created_at: datetime
  # #endregion Schemas.Agent.MessageItem
  
  
  # #region Schemas.Agent.HistoryResponse [C:1] [TYPE Class] [SEMANTICS agent,schema,history]
  # @ingroup Schemas
> class HistoryResponse(BaseModel):
>     items: list[MessageItem]
>     has_next: bool = False
>     conversation_id: str | None = None
  # #endregion Schemas.Agent.HistoryResponse
  
  
  # #region Schemas.Agent.DeleteResponse [C:1] [TYPE Class] [SEMANTICS agent,schema,delete]
  # @ingroup Schemas
> class DeleteResponse(BaseModel):
>     deleted: bool = True
  # #endregion Schemas.Agent.DeleteResponse
  
  
  # #region Schemas.Agent.ServiceTokenRequest [C:1] [TYPE Class] [SEMANTICS agent,schema,auth]
  # @ingroup Schemas
> class ServiceTokenRequest(BaseModel):
>     service_secret: str
  # #endregion Schemas.Agent.ServiceTokenRequest
  
  
  # #region Schemas.Agent.ServiceTokenResponse [C:1] [TYPE Class] [SEMANTICS agent,schema,auth]
  # @ingroup Schemas
> class ServiceTokenResponse(BaseModel):
>     access_token: str
>     token_type: str = "bearer"
>     expires_in: int = 86400
>     role: str = "agent"
  # #endregion Schemas.Agent.ServiceTokenResponse
  
  
  # #region Schemas.Agent.SaveConversationRequest [C:1] [TYPE Class] [SEMANTICS agent,schema,save]
  # @ingroup Schemas
> class SaveConversationRequest(BaseModel):
>     conversation_id: str
>     title: str = ""
>     user_id: str = "admin"
>     messages: list[dict] = []
  # #endregion Schemas.Agent.SaveConversationRequest
  # #endregion Schemas.Agent
