Python agents
Agents contracts and source references for Python.
AgentConfig takes model_ref, system_prompt, max_steps, and generation options. ToolLoopAgent separately takes the config, model, tool registry, and tool executor. await agent.run(input_text) returns an AgentOutput with text, messages, steps, and usage. The run owns lifecycle transitions. Handle Forge errors at the application boundary.
A bounded run
This complete function accepts a model already configured by the caller. No tools are registered. Supply a model supported by your application and handle the returned error or exception at the caller. This example does not provision provider credentials, identity or deployment.
from forge.agent.agent import AgentConfig, AgentOutput
from forge.agent.tool_loop import ToolLoopAgent
from forge.core.model import LanguageModel
from forge.tool.approval import ApprovalHandler
from forge.tool.execution import ToolExecutor
from forge.tool.registry import ToolRegistry
async def run_agent(
model: LanguageModel,
approval: ApprovalHandler,
provider_ref: str,
prompt: str,
) -> AgentOutput:
registry = ToolRegistry()
executor = ToolExecutor(registry, approval_handler=approval)
agent = ToolLoopAgent(
AgentConfig(model_ref=provider_ref, max_steps=3),
model,
registry,
executor,
)
return await agent.run(prompt)The caller must supply an ApprovalHandler; the example does not silently select automatic approval.
Python reference
Each reference records the source path, hash and declaration inventory for this language. Start at the import boundary before using a symbol found in a deeper implementation file.
Lifecycle and failures
Choose finite iteration and token budgets, handle generation and execution failures, and release resources on termination. Inspect the returned usage and completion state before recording a successful run. The SDK health/lifecycle object describes local runtime state; it is not a deployment health check.