Agent Smolagents¶

Agent Smolagents — mvp.agent_smolagents

Cluster: Agents & LLM | Type: component | MCP Tools: 26

Overview¶

Production-hardened HuggingFace smolagents tool-use agent wrapper supporting both CodeAgent and ToolCallingAgent variants. Generic runs default to safer ToolCallingAgent; CodeAgent is explicit and exposes bounded executor settings. Registered tools are opt-in by registry name during execution. Uses a LiteLLM-backed model so any OpenAI-compatible endpoint can serve as the reasoning engine; includes circuit breaker, retry, structured logging, metrics, failed-run persistence, read-only source-health/capability reporting, and top-level completion_state / admission_verdict envelope fields.

When to use:

• Running tool-augmented reasoning loops where the agent writes and executes Python code to solve tasks
• Integrating HuggingFace smolagents into the G6 pipeline with production-grade resilience
• Benchmarking code vs toolcalling agent strategies on the same task with step-level trace capture

Example:

from mvp.agent_smolagents import AgentSmolagentsBlock, SmolagentsInput

block = AgentSmolagentsBlock(name="smolagents")
result = block.infer(SmolagentsInput(
    task="Calculate the 10th Fibonacci number using code.",
    agent_type="code",
    max_steps=5,
    model="gpt-4o-mini",
))
# result.ok → True; result.value → SmolagentsOutput with final_answer, tool_calls

Works well with: agent_openai, cegis, solver

Public API¶

AdmissionDecision¶

Decision on whether a smolagents code-execution run may be admitted.

AgentSmolagentsPlanner¶

Runtime-first facade that falls back to real deterministic floor logic.

Methods:

decide(goal: str, context: str = '') -> AgentSmolagentsDecision¶

decide_admission(task_preview: str, agent_type: str, requested_imports: tuple[str, ...] | list[str], requested_executor: str, deterministic_allowed: bool) -> AdmissionDecision¶

ToolCall(BaseModel)¶

A single tool invocation recorded during agent execution.

SmolagentsInput(BaseModel)¶

Input to AgentSmolagentsBlock.

SmolagentsOutput(BaseModel)¶

Output from AgentSmolagentsBlock.

AgentSmolagentsBlock(LifecycleMixin, AIBlock[SmolagentsInput, SmolagentsOutput, None])¶

Production-hardened HuggingFace smolagents tool-use agent block.

Methods:

infer(data: SmolagentsInput) -> Result[SmolagentsOutput]¶

describe() -> dict[str, Any]¶

Return read-only source health and capabilities without executing an agent.

MCPSmolagentsInput(BaseModel)¶

MCPSmolagentsOutput(BaseModel)¶

MCPSmolagentsRecord(BaseModel)¶

AdaptSmolagentsMCPBlock(AIBlock[MCPSmolagentsInput, MCPSmolagentsOutput, dict])¶

Full-featured smolagents block with SQLite persistence.

Methods:

infer(data: MCPSmolagentsInput) -> Result[MCPSmolagentsOutput]¶

SmolagentsStore¶

Sync SQLite smolagents store with 5 tables.

Constructor:

Methods:

save_session(name: str, model: str, agent_type: str, max_steps: int, tools_json: str, provider: str, notes: str, config_json: str) -> str¶

load_session(name: str) -> dict[str, Any] | None¶

list_sessions(limit: int = 50) -> list[dict[str, Any]]¶

delete_session(name: str) -> bool¶

add_run(task: str, model: str, agent_type: str, provider: str, final_answer: str, steps_taken: int, duration_ms: int, tool_calls_json: str, success: bool, notes: str, tags: list[str]) -> str¶

get_run(run_id: str) -> dict[str, Any] | None¶

query_runs(query: str = '', limit: int = 50) -> list[dict[str, Any]]¶

summarize_runs() -> dict[str, Any]¶

register_tool(name: str, description: str, code: str, inputs_json: str, output_type: str, tags: list[str]) -> str¶

get_tool(name: str) -> dict[str, Any] | None¶

list_tools(limit: int = 50) -> list[dict[str, Any]]¶

delete_tool(name: str) -> bool¶

add_log(run_id: str, step_num: int, step_type: str, content: str, tool_name: str) -> str¶

query_logs(run_id: str = '', limit: int = 50) -> list[dict[str, Any]]¶

search_runs(query: str, top_k: int = 5) -> list[dict[str, Any]]¶

search_tools(query: str, top_k: int = 5) -> list[dict[str, Any]]¶

count_all() -> dict[str, int]¶

Functions¶

build_agent_smolagents_planner(default_enabled: bool = True, llm_backend: str | None = None) -> AgentSmolagentsPlanner | None¶

Single shared factory for the agentic admission planner (ON-BY-DEFAULT).

MCP Tools¶