{
  "name": "forge.agent",
  "language": "python",
  "version": "0.1.0",
  "description": "Python agent package; imports are explicit from this package.",
  "manifest": "forge-py/pyproject.toml",
  "manifestSha256": "7f96957378b21995bf2e583af2afd1b9e6fb3b0089ff3559d62c7e012a034696",
  "status": "source-reference",
  "registryPublicationVerified": false,
  "route": "/libraries/python/agent",
  "features": {},
  "files": [
    {
      "path": "forge-py/src/forge/agent/__init__.py",
      "sha256": "8b79efd8425c2ad1e89f3a840b2a1dc9a3e55127e1f4e4060280ab8bf9bc1576",
      "artifactSha256": "17a72557dc70fde053f94d7373b940f3342552be47c3722688bb056bffb15c80",
      "url": "/reference/source/forge-py/src/forge/agent/__init__.py.txt",
      "declarations": []
    },
    {
      "path": "forge-py/src/forge/agent/agent.py",
      "sha256": "40139c2d88cd34a31006687350806146f230da078d670a3d2441b561119d7ec9",
      "artifactSha256": "e044907e10dd376697b9256b732f874c60cda8788307bf66558fd01c88c3f9f7",
      "url": "/reference/source/forge-py/src/forge/agent/agent.py.txt",
      "declarations": [
        {
          "name": "AgentConfig",
          "line": 21,
          "signature": "class AgentConfig()",
          "documentation": "Configuration for an Agent.\n\nArgs:\n    model_ref: Provider reference (e.g., \"openai:gpt-4o\").\n    system_prompt: Optional system prompt for the agent.\n    max_steps: Maximum tool loop iterations (default: 10).\n    options: Default generation options."
        },
        {
          "name": "AgentOutput",
          "line": 38,
          "signature": "class AgentOutput()",
          "documentation": "Output from an agent run.\n\nArgs:\n    text: The final text output.\n    messages: The complete message history.\n    steps: Number of tool loop steps executed.\n    usage: Aggregate token usage."
        },
        {
          "name": "Agent",
          "line": 54,
          "signature": "class Agent(ABC)",
          "documentation": "Abstract base class for all Forge agents.\n\nEvery agent maintains a lifecycle state machine and health profile.\nConcrete implementations define the ``run`` method.\n\nANVIL Spec section 5.1: Lifecycle State Machine.\nANVIL Spec section 6.1: Cognitive Interface."
        },
        {
          "name": "Agent.__init__",
          "line": 64,
          "signature": "def __init__(self, config: AgentConfig) -> None",
          "documentation": ""
        },
        {
          "name": "Agent.config",
          "line": 70,
          "signature": "def config(self) -> AgentConfig",
          "documentation": "Return the agent configuration.\n\nReturns:\n    The AgentConfig."
        },
        {
          "name": "Agent.health",
          "line": 79,
          "signature": "def health(self) -> HealthProfile",
          "documentation": "Return the health profile.\n\nReturns:\n    The HealthProfile."
        },
        {
          "name": "Agent.lifecycle",
          "line": 88,
          "signature": "def lifecycle(self) -> LifecycleManager",
          "documentation": "Return the lifecycle manager.\n\nReturns:\n    The LifecycleManager."
        },
        {
          "name": "Agent.state",
          "line": 97,
          "signature": "def state(self) -> LifecycleState",
          "documentation": "Return the current lifecycle state.\n\nReturns:\n    The current LifecycleState."
        },
        {
          "name": "Agent.run",
          "line": 106,
          "signature": "async def run(self, input_text: str) -> AgentOutput",
          "documentation": "Run the agent with the given input.\n\nArgs:\n    input_text: The user input to process.\n\nReturns:\n    The agent output.\n\nRaises:\n    ForgeError: If the agent encounters an error."
        }
      ]
    },
    {
      "path": "forge-py/src/forge/agent/loop_control.py",
      "sha256": "20096e1ac88ea3dbbe85630f48dd6609637b1b731d715c79a2cbd08860f84008",
      "artifactSha256": "8ed73ab20d8f56959f5c4a4714bef43f40bbf33b573a9773faf5a7718fb46f82",
      "url": "/reference/source/forge-py/src/forge/agent/loop_control.py.txt",
      "declarations": [
        {
          "name": "LoopControl",
          "line": 13,
          "signature": "class LoopControl(ABC)",
          "documentation": "Abstract base class for tool loop termination control.\n\nImplementations decide whether to continue the tool loop after each step."
        },
        {
          "name": "LoopControl.should_continue",
          "line": 20,
          "signature": "def should_continue(self, step: int, result: GenerateResult) -> bool",
          "documentation": "Decide whether the tool loop should continue.\n\nArgs:\n    step: The current step number (0-indexed).\n    result: The result from the latest generation.\n\nReturns:\n    True if the loop should continue."
        },
        {
          "name": "StopOnCompleteControl",
          "line": 32,
          "signature": "class StopOnCompleteControl(LoopControl)",
          "documentation": "Stop the loop when the model produces a complete response (no tool calls).\n\nThis is the default loop control strategy."
        },
        {
          "name": "StopOnCompleteControl.should_continue",
          "line": 38,
          "signature": "def should_continue(self, step: int, result: GenerateResult) -> bool",
          "documentation": "Continue only if the model requested tool calls.\n\nArgs:\n    step: The current step number.\n    result: The generation result.\n\nReturns:\n    True if the finish reason is TOOL_CALLS."
        },
        {
          "name": "MaxStepsControl",
          "line": 51,
          "signature": "class MaxStepsControl(LoopControl)",
          "documentation": "Stop the loop after a maximum number of steps.\n\nArgs:\n    max_steps: The maximum number of steps."
        },
        {
          "name": "MaxStepsControl.__init__",
          "line": 58,
          "signature": "def __init__(self, max_steps: int) -> None",
          "documentation": ""
        },
        {
          "name": "MaxStepsControl.should_continue",
          "line": 61,
          "signature": "def should_continue(self, step: int, result: GenerateResult) -> bool",
          "documentation": "Continue if under the step limit and the model wants to call tools.\n\nArgs:\n    step: The current step number.\n    result: The generation result.\n\nReturns:\n    True if under the limit and model requested tool calls."
        }
      ]
    },
    {
      "path": "forge-py/src/forge/agent/messaging.py",
      "sha256": "1a5fba4ecbf1f4c97660e917e5d3e8153b62c83dbb8b1e4370b39d7536cbab22",
      "artifactSha256": "6c3e1d3648fa5db948c75a78c9816785a145a209074939436479a53cc8b7bc0f",
      "url": "/reference/source/forge-py/src/forge/agent/messaging.py.txt",
      "declarations": [
        {
          "name": "AgentMessage",
          "line": 15,
          "signature": "class AgentMessage()",
          "documentation": "A message between agents.\n\nUsed for sub-agent delegation and multi-agent orchestration.\n\nArgs:\n    sender_did: The sender agent's DID.\n    recipient_did: The recipient agent's DID.\n    content: The message content.\n    protocol: The communication protocol used.\n    message_type: The message type (e.g., \"request\", \"response\").\n    timestamp: When the message was created.\n    metadata: Optional additional metadata."
        },
        {
          "name": "AgentMessage.to_dict",
          "line": 38,
          "signature": "def to_dict(self) -> dict[str, Any]",
          "documentation": "Serialize to a dictionary.\n\nReturns:\n    Dictionary representation."
        }
      ]
    },
    {
      "path": "forge-py/src/forge/agent/subagent.py",
      "sha256": "6d51e16b16ce1e9d0ac39262095f20c5069b2e6f2441370eaaa2f8cf26992894",
      "artifactSha256": "e1447ceddc8162c587eca32c9ca04c7dce77cfd464446d9abc793696390b8401",
      "url": "/reference/source/forge-py/src/forge/agent/subagent.py.txt",
      "declarations": [
        {
          "name": "SubAgentConfig",
          "line": 12,
          "signature": "class SubAgentConfig()",
          "documentation": "Configuration for creating a sub-agent.\n\nThe child agent receives derived identity and narrowed capabilities.\nChild capabilities must be a strict subset of parent capabilities.\n\nANVIL Spec section 11.2: Lineage Propagation.\n\nArgs:\n    name: The sub-agent name (used in DID derivation).\n    model_ref: Provider reference for the sub-agent.\n    system_prompt: Optional system prompt.\n    max_steps: Maximum tool loop iterations.\n    capabilities: List of capability strings requested for the child."
        }
      ]
    },
    {
      "path": "forge-py/src/forge/agent/tool_loop.py",
      "sha256": "acf317d81c79ac6b54a1044878e269c7e3ace7baa4a340804819ca9ae104afb2",
      "artifactSha256": "1ffa20d4181f98ab20a45b3080a274b9c807fda82fdec23e5f45b5682e0d8cd6",
      "url": "/reference/source/forge-py/src/forge/agent/tool_loop.py.txt",
      "declarations": [
        {
          "name": "ToolLoopAgent",
          "line": 29,
          "signature": "class ToolLoopAgent(Agent)",
          "documentation": "An agent that executes a tool loop until completion.\n\nThe tool loop pattern:\n1. Send messages to the model\n2. If model returns tool calls, execute them\n3. Append tool results to messages\n4. Repeat until model returns a final text response or limit reached\n\nANVIL Spec sections 6.1, 8.5-8.7.\n\nArgs:\n    config: Agent configuration.\n    model: The language model to use.\n    tool_registry: The registry of available tools.\n    tool_executor: The tool executor.\n    loop_control: Optional loop termination control.\n\nExample:\n    >>> # With a mock model and tools:\n    >>> # agent = ToolLoopAgent(config, model, registry, executor)\n    >>> # output = await agent.run(\"Hello\")"
        },
        {
          "name": "ToolLoopAgent.__init__",
          "line": 53,
          "signature": "def __init__(self, config: AgentConfig, model: LanguageModel, tool_registry: ToolRegistry, tool_executor: ToolExecutor, loop_control: LoopControl | None=None) -> None",
          "documentation": ""
        },
        {
          "name": "ToolLoopAgent.run",
          "line": 71,
          "signature": "async def run(self, input_text: str) -> AgentOutput",
          "documentation": "Run the tool loop agent with the given input.\n\nTransitions through lifecycle states:\nCreated -> Initializing -> Active -> (processing) -> Terminating -> Terminated\n\nArgs:\n    input_text: The user input to process.\n\nReturns:\n    The agent output with final text, messages, step count, and usage.\n\nRaises:\n    ForgeStopConditionError: If the maximum step limit is reached.\n    ForgeError: If any other error occurs during execution."
        }
      ]
    },
    {
      "path": "forge-py/src/forge/agent/workflow.py",
      "sha256": "03aec45ac26d7a43e6e807fb07c1586e8a54c1fee84cea1fccfe55f4d10f4f2a",
      "artifactSha256": "acc6c050a3dd2f71e219430816486f6a066ca9c2219bc5317201a26f0638e2e2",
      "url": "/reference/source/forge-py/src/forge/agent/workflow.py.txt",
      "declarations": [
        {
          "name": "WorkflowStep",
          "line": 13,
          "signature": "class WorkflowStep()",
          "documentation": "A single step in a workflow.\n\nArgs:\n    name: Human-readable step name.\n    agent_ref: Reference to the agent to execute.\n    input_template: Input template with ``{variable}`` placeholders.\n    output_key: Key to store the step's output for subsequent steps."
        },
        {
          "name": "SequentialWorkflow",
          "line": 29,
          "signature": "class SequentialWorkflow()",
          "documentation": "A workflow that executes steps in sequence.\n\nEach step's output is available as a variable in subsequent steps'\ninput templates.\n\nANVIL Spec section 13: Multi-Agent Orchestration.\n\nArgs:\n    steps: The ordered list of workflow steps.\n\nExample:\n    >>> wf = SequentialWorkflow([\n    ...     WorkflowStep(\"research\", \"research-agent\", \"{input}\", \"research_result\"),\n    ...     WorkflowStep(\"summarize\", \"summary-agent\", \"{research_result}\", \"summary\"),\n    ... ])\n    >>> len(wf.steps)\n    2"
        },
        {
          "name": "SequentialWorkflow.__init__",
          "line": 49,
          "signature": "def __init__(self, steps: list[WorkflowStep]) -> None",
          "documentation": ""
        },
        {
          "name": "SequentialWorkflow.steps",
          "line": 53,
          "signature": "def steps(self) -> list[WorkflowStep]",
          "documentation": "Return the workflow steps.\n\nReturns:\n    List of WorkflowStep instances."
        },
        {
          "name": "SequentialWorkflow.resolve_input",
          "line": 61,
          "signature": "def resolve_input(self, template: str, context: dict[str, str]) -> str",
          "documentation": "Resolve an input template against a context of previous outputs.\n\nArgs:\n    template: The input template with ``{variable}`` placeholders.\n    context: Dictionary of variable names to values.\n\nReturns:\n    The resolved input string."
        }
      ]
    }
  ]
}