Public declaration syntax from forge-rs/crates/forge-contracts/src/runtime.rs Original source SHA-256: 4dbb8f13325f3c7f0ba99318e6c9fef05643056919ee22fc53f011f00cc25230 Function bodies and constant values are omitted. This is not the complete implementation. Source line 60 pub const CONTRACT_VERSION: &str; Source line 88 #[derive(Debug, Clone, Serialize, Deserialize)] pub struct AgentCreateRequest { /// Human-readable name for the agent (e.g., "code-reviewer"). pub agent_name: String, /// The provider:model reference (e.g., "anthropic:claude-sonnet-4-5-20250929"). pub provider_ref: String, /// Optional system prompt prepended to every LLM call. pub system_prompt: Option, /// Tool definitions available to this agent. pub tools: Vec, /// Maximum tool loop steps before forced termination. pub max_steps: u32, /// Aut0 organization ID (org-level context). pub org_id: Option, /// Aut0 department ID (department-level context). pub department_id: Option, /// Role within the organization (e.g., "senior-reviewer", "pm"). pub role: Option, /// Parent agent DID for sub-agent derivation. When `None`, the agent /// is a root-level agent derived from an HMR/MHR. pub parent_agent_did: Option, /// Arbitrary key-value metadata for Aut0-specific context. pub metadata: std::collections::BTreeMap } Source line 138 #[derive(Debug, Clone, PartialEq, Eq, Hash)] pub struct AgentHandle { } Source line 147 pub fn new(id: impl Into, did: impl Into) -> Self; Source line 155 pub fn id(&self) -> &str; Source line 160 pub fn did(&self) -> &str; Source line 169 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] pub enum AgentLifecycleCommand { /// Transition from Initializing to Ready, then to Running. Start, /// Transition from Running to Paused. Pause, /// Transition from Paused to Running. Resume, /// Transition from any state to Terminated. Terminate { /// Optional reason for termination. reason: Option, }, } Source line 187 #[derive(Debug, Clone, Serialize, Deserialize)] pub struct AgentStatus { /// The agent's OAS DID. pub did: String, /// Current ANVIL lifecycle state. pub lifecycle_state: LifecycleState, /// Current health profile snapshot. pub health: HealthProfile, /// Number of tool loop steps completed. pub steps_completed: u32, /// Number of tool loop steps remaining before max_steps. pub steps_remaining: u32, /// Whether the agent is currently executing a tool call. pub executing_tool: bool, /// The provider:model reference the agent is using. pub provider_ref: String, /// Aut0 metadata passed at creation. pub metadata: std::collections::BTreeMap } Source line 215 #[derive(Debug, Clone, Serialize, Deserialize)] pub struct AgentRunResult { /// The final text output from the agent, if any. pub output_text: Option, /// Structured output as JSON, if the agent produced structured output. pub output_json: Option, /// Total tool invocations during the run. pub tool_invocations: u32, /// Total LLM inference calls during the run. pub inference_calls: u32, /// Total tokens consumed (input + output). pub total_tokens: u64, /// Whether the agent terminated normally or was force-stopped. pub terminated_normally: bool, /// The final lifecycle state. pub final_state: LifecycleState } Source line 262 #[async_trait] pub trait AgentRuntimeContract: Send + Sync { /// Creates a new agent in the Forge runtime. /// /// The agent starts in `Initializing` state. Call `lifecycle_command` /// with `Start` to advance it to `Running`. /// /// # Arguments /// /// * `request` - The agent creation parameters including identity, /// provider, tools, and Aut0-specific metadata. /// /// # Returns /// /// An opaque handle to the created agent. /// /// # Errors /// /// - `ContractError::AgentCreationFailed` if the configuration is invalid. /// - `ContractError::IdentityDerivationFailed` if identity cannot be derived. /// - `ContractError::NoProviderAvailable` if the provider ref cannot be resolved. async fn create_agent(&self, request: AgentCreateRequest) -> ContractResult; /// Issues a lifecycle command to an existing agent. /// /// # Arguments /// /// * `handle` - The agent to command. /// * `command` - The lifecycle transition to perform. /// /// # Returns /// /// The new status after the transition. /// /// # Errors /// /// - `ContractError::AgentNotFound` if the handle is invalid. /// - `ContractError::InvalidLifecycleTransition` if the transition /// violates the ANVIL state machine. async fn lifecycle_command( &self, handle: &AgentHandle, command: AgentLifecycleCommand, ) -> ContractResult; /// Queries the current status of an agent. /// /// # Arguments /// /// * `handle` - The agent to query. /// /// # Returns /// /// A snapshot of the agent's lifecycle, health, and execution state. /// /// # Errors /// /// - `ContractError::AgentNotFound` if the handle is invalid. async fn get_status(&self, handle: &AgentHandle) -> ContractResult; /// Runs an agent to completion with the given input. /// /// This is a convenience method that starts the agent (if not already /// running), sends the input through the tool loop, and blocks until /// termination or max_steps. /// /// # Arguments /// /// * `handle` - The agent to run. /// * `input` - The user/task input string. /// /// # Returns /// /// The execution result including output, tool counts, and token usage. /// /// # Errors /// /// - `ContractError::AgentNotFound` if the handle is invalid. /// - `ContractError::InvalidLifecycleTransition` if the agent is in /// a state that cannot transition to Running. async fn run_to_completion( &self, handle: &AgentHandle, input: &str, ) -> ContractResult; /// Lists all active agents matching an optional filter. /// /// # Arguments /// /// * `org_id` - Filter by organization. `None` returns all. /// * `department_id` - Filter by department. `None` returns all in org. /// /// # Returns /// /// Handles for all matching agents. async fn list_agents( &self, org_id: Option<&str>, department_id: Option<&str>, ) -> ContractResult>; }