Struct Session 

pub struct Session {

    pub id: SessionId,
    pub organization_id: String,
    pub harness_id: HarnessId,
    pub agent_id: Option<AgentId>,
    pub agent_version_id: Option<AgentVersionId>,
    pub agent_identity_id: Option<AgentIdentityId>,
    pub owner_principal_id: PrincipalId,
    pub resolved_owner_user_id: Option<Uuid>,
    pub owner: Option<PrincipalSummary>,
    pub effective_owner: Option<PrincipalSummary>,
    pub title: Option<String>,
    pub locale: Option<String>,
    pub preview: Option<String>,
    pub output_preview: Option<String>,
    pub tags: Vec<String>,
    pub model_id: Option<ModelId>,
    pub capabilities: Vec<AgentCapabilityConfig>,
    pub tools: Vec<ToolDefinition>,
    pub mcp_servers: ScopedMcpServers,
    pub system_prompt: Option<String>,
    pub initial_files: Vec<InitialFile>,
    pub hints: Option<HashMap<String, Value>>,
    pub network_access: Option<NetworkAccessList>,
    pub max_iterations: Option<usize>,
    pub status: SessionStatus,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
    pub started_at: Option<DateTime<Utc>>,
    pub finished_at: Option<DateTime<Utc>>,
    pub usage: Option<TokenUsage>,
    pub is_pinned: Option<bool>,
    pub active_schedule_count: Option<u32>,
    pub features: Vec<String>,
    pub parent_session_id: Option<SessionId>,
    pub subagent_name: Option<String>,
    pub subagent_task: Option<String>,
    pub subagent_status: Option<SubagentStatus>,
    pub blueprint_id: Option<String>,
    pub blueprint_config: Option<Value>,
}

Session - instance of agentic loop execution. A session represents a single conversation with an agent.

Fields

id: SessionId

Unique identifier for the session (format: session_{32-hex}).

organization_id: String

Organization this session belongs to (format: org_{32-hex}).

harness_id: HarnessId

ID of the harness for this session (format: harness_{32-hex}).

agent_id: Option<AgentId>

ID of the agent working in this session (format: agent_{32-hex}). Optional.

agent_version_id: Option<AgentVersionId>

Immutable agent version captured when the session was created or rebound.

agent_identity_id: Option<AgentIdentityId>

Optional resident agent identity for unattended/background execution.

owner_principal_id: PrincipalId

Owning principal for this session.

resolved_owner_user_id: Option<Uuid>

Denormalized effective human owner of the owning principal lineage.

owner: Option<PrincipalSummary>

Owning principal summary.

effective_owner: Option<PrincipalSummary>

Effective human owner summary.

title: Option<String>

Human-readable title for the session.

locale: Option<String>

Locale for localized agent behavior and formatting (BCP 47, e.g. uk-UA).

preview: Option<String>

Preview text from the first user message (truncated).

output_preview: Option<String>

Preview text from the last assistant response (truncated).

tags: Vec<String>

Tags for organizing and filtering sessions.

model_id: Option<ModelId>

LLM model ID to use for this session (format: model_{32-hex}). Overrides the agent’s default model if set.

capabilities: Vec<AgentCapabilityConfig>

Session-level capabilities (additive to agent capabilities). Applied after agent capabilities when building RuntimeAgent.

tools: Vec<ToolDefinition>

Client-side tools for this session (additive to agent tools).

mcp_servers: ScopedMcpServers

Remote MCP servers scoped to this session only.

system_prompt: Option<String>

Session-level system prompt override. Prepended to the agent’s system prompt when building RuntimeAgent.

initial_files: Vec<InitialFile>

Session-level initial files (additive to agent initial_files). Files with matching paths override agent/harness files; new paths are appended.

hints: Option<HashMap<String, Value>>

Session-level client hints — arbitrary key-value pairs declared by the client at session creation time. These are defaults for every turn; per-message controls.hints override these key-by-key (shallow merge).

Examples: {"setup_connection": true, "rich_media": true}

network_access: Option<NetworkAccessList>

Network access list controlling which hosts/URLs this session can reach. Merged with harness and agent layers (allowed: intersect, blocked: union).

max_iterations: Option<usize>

Maximum number of LLM iterations per turn for this session.

status: SessionStatus

Current execution status of the session.

created_at: DateTime<Utc>

Timestamp when the session was created.

updated_at: DateTime<Utc>

Timestamp when the session was last updated.

started_at: Option<DateTime<Utc>>

Timestamp when the session started executing.

finished_at: Option<DateTime<Utc>>

Timestamp when the session finished (completed or failed).

usage: Option<TokenUsage>

Cumulative token usage for all LLM calls in this session.

is_pinned: Option<bool>

Whether this session is pinned by the current user. Only populated when the request has an authenticated user context.

active_schedule_count: Option<u32>

Number of active (enabled) schedules for this session. Populated when the session is fetched for API responses.

features: Vec<String>

Aggregated UI features from all active capabilities (harness + agent + session). Computed at read time from the capability registry. Known features: “file_system”, “schedules”, “secrets”, “key_value”, “sql_database”, “leased_resources”.

parent_session_id: Option<SessionId>

Parent session that spawned this subagent. NULL for top-level sessions.

subagent_name: Option<String>

Human-readable subagent name (“Test Runner”), unique per parent.

subagent_task: Option<String>

Original task description given to this subagent.

subagent_status: Option<SubagentStatus>

Subagent lifecycle status: spawning, running, completed, failed, cancelled.

blueprint_id: Option<String>

Blueprint ID. When set, reason_activity and act_activity build RuntimeAgent from the blueprint definition instead of from harness_id/agent_id.

blueprint_config: Option<Value>

Validated config passed by host at blueprint spawn time. Example: {"target_repo": "acme/everruns"}.

Trait Implementations

impl Clone for Session

fn clone(&self) -> Session

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Session

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Session

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl From<&Session> for AgentConfigOverlay

fn from(s: &Session) -> Self

Converts to this type from the input type.

impl HasAuditTargetId for Session

fn audit_target_id(&self) -> Option<String>

impl Serialize for Session

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.