agently-runtime

name	agently-runtime
description	Use when the user wants Agently runtime extension capabilities: Action Runtime, built-in action packages, legacy tool compatibility, MCP access, Execution Environment lifecycle, FastAPIHelper or streaming API exposure, auto-function helpers, KeyWaiter, or optional agently-devtools observation, evaluation, and playground integration.

Agently Runtime

Use this skill when the app needs model-callable capabilities, managed execution dependencies, service exposure, or development/runtime tooling around an existing request or workflow design.

If the owner layer is still undecided, start with agently-playbook. If the problem is multi-step orchestration, use agently-triggerflow first and return here for Actions, Execution Environment, service, or DevTools details.

Route Inside This Skill

• Action Runtime, @agent.action_func, agent.use_actions(...), built-in Search/Browse, sandbox actions, or legacy tools -> references/actions-runtime.md
• Action vs Execution Environment boundaries, agent.enable_* helpers, provider lifecycle, managed MCP/sandbox/process/browser/SQLite resources -> references/actions-execution-environment.md
• observation, evaluation, playground, local logs, or agently-devtools -> references/devtools.md

Native-First Rules

• prefer @agent.action_func and agent.use_actions(...); tool_func, use_tool, use_tools, and agently.builtins.tools are compatibility surfaces
• use built-in web packages through from agently.builtins.actions import Search, Browse and mount with agent.use_actions(Search(...)) / agent.use_actions(Browse(...))
• do not invent enable_search(...); Search configuration belongs to the Search package/executor, not Execution Environment
• for durable multi-turn task records, prefer agent.use_workspace(...); for model-callable local file actions, use agent.enable_workspace_file_actions(...), which exposes the current Workspace file working tree and inherits agent.workspace.files_root when a Foundation Workspace is configured
• use workspace.build_context(...) for Workspace-backed Recall; advanced model-assisted planners, vector retrieval, rerankers, and compressors should plug into RecallPlanner/Retriever/ContextBuilder instead of becoming WorkLoop or Action shortcuts
• for explicit TriggerFlow loops, store structured observations and decisions in Workspace, link decisions to evidence with workspace.link(...), recover state with workspace.latest_checkpoint(...), and inspect backend wiring with workspace.capabilities()
• for app developers, prefer agent.enable_python(...), agent.enable_shell(...), agent.enable_workspace_file_actions(...), agent.enable_nodejs(...), and agent.enable_sqlite(...) before direct manager/provider APIs
• for instruction-heavy Actions, expect later model rounds to see compact execution digests and artifact refs; use agent.action.read_action_artifact(...) only when full raw code, command output, SQL results, page content, or logs are needed
• treat Agently.execution_environment as an advanced framework/plugin surface for lifecycle, policy, approval, health, and release
• Action executors should declare or consume managed resources instead of secretly owning long-lived MCP clients, sandboxes, browsers, SQLite connections, or process runners
• keep permission profiles explicit: search-only, local-files-only, network-read, install-capable shell, or trusted executor
• treat agently-devtools as optional PyPI-installed tooling; wire observation through public bridge APIs, not source-repo paths
• for framework internals, preserve Agently's core module style: class-owned runtime behavior, typed data contracts, protocol/handler seams for replacement, and high-level packages outside agently/core when they compose several core systems
• for framework-side Skills Executor work, prefer the Agently.skills_executor facade backed by the builtin SkillsExecutor plugin; Agently 4.1.2.5 did not ship Agently.skills as a compatibility alias
• for Agently 4.1.3 Skills runtime work, prefer Action-like management: declare installed ids or remote source selectors on agent.use_skills(...) and let Skills Executor lazily discover, install, and mount selected capabilities; keep install_skills_pack(...) for prewarming, offline mirrors, deterministic CI fixtures, and explicit registry maintenance
• use install_skills(...) for one local Skill directory during authoring/smoke tests; use agent.run_skills_task(...) for explicit Skills execution; remote selectors may use git URLs, GitHub shorthand such as anthropics/skills, and subpath= when selecting one Skill from a pack
• for explicit Skills execution, effort="fast" maps to the low-overhead single-shot path, effort="normal" runs the full preflight -> research -> plan -> execute -> verify -> reflect -> finalize runtime chain, and effort="max" increases retry budget for that chain
• for application-specific Skills action strategies, use Agently.skills_executor.register_effort_strategy(name, handler) and invoke it with effort=name; the handler should compose model requests, ActionRuntime/MCP, ExecutionEnvironment, TriggerFlow, or Dynamic Task through the Agent runtime context instead of building a parallel tool dispatcher
• Skills effort strategy handlers follow the SkillsEffortStrategyHandler protocol with keyword arguments context, task, plan, output_format, effort, and effort_config; builtin strategies single_shot, runtime_chain, staged, and react are exposed through the same strategy table and can be inspected with list_effort_strategies(); their reference implementations live under the Agently builtin Skills Executor modules/effort_strategies/ package
• for MCP, prefer Streamable HTTP URLs for service integrations (agent.use_mcp("https://host/mcp")), use headers= for URL auth, and use MCP config dictionaries for stdio/multi-server local integrations; treat SSE as a legacy compatibility transport
• treat Agent quick prompt methods as configuration for every Agent execution surface: agent.input(...).output(...).run_skills_task(...) maps the rendered prompt snapshot to the Skill task and maps output / output_format to the Skills execution output / output_format contract; semantic_outputs= is only a deprecated compatibility alias for direct Skills execution, while Dynamic Task still uses semantic_outputs inside TaskDAG specs
• for framework-side Skills execution, keep standard SKILL.md as the only capability definition; selected Skills default to single_shot model requests using their full Markdown guidance, while declared staged/react strategies should compose TriggerFlow and ActionFlow/ActionRuntime rather than adding a Skills-local executor
• for Skills react tool use, delegate model-owned action planning and execution to the Agent ActionRuntime so action/MCP kwargs schemas, policy, approvals, concurrency, and managed resources stay on the Action layer
• for selected Skills that declare MCP or Bash/script capabilities, expect the Skills Executor to mount runtime actions automatically before execution: MCP declarations route through agent.use_mcp(...), Bash/script declarations route through managed enable_shell(...) actions scoped to the installed Skill directory, and local command/script mounts require auto_allow=True or an approval handler
• for missing declared Skills capabilities, allow executor synthesis only for safely classified pure Python sandbox work such as calculation, parsing, validation, transformation, or format conversion; never synthesize business, network, filesystem, messaging, payment, database, browser, shell, or MCP capabilities, and require a real Action/MCP/connector instead
• for Agently 4.1.2.x auto-orchestration work, treat agent.use_skills(...).input(...).start() as route-candidate registration owned by the Agent route planner, not prompt-only Skills guidance injection by default
• for ambiguous optional route candidates, keep submitted Dynamic Task and required Skills deterministic, but let the model choose among optional auto Dynamic Task, model-decision Skills, and ordinary Action-backed model request routes
• for framework-side Skills, treat standard SKILL.md as the only capability definition; Agently install metadata and decision cards are descriptive runtime aids, not authoring formats or availability gates
• for Skills actions, use Action/ExecutionEnvironment approval and resource boundaries; use TriggerFlow pause_for(...) / continue_with(...) for durable waits instead of storing pending approvals on a Skills snapshot
• keep Agent auto-orchestration behind the AgentOrchestrator plugin protocol: core owns the public agent.create_execution() entrypoint, while the active plugin owns route planning, execution, and stream bridging
• for unified Agent execution/result work, prefer a response-style agent.create_execution() object with data/text/meta/stream consumption; use TriggerFlow runtime stream plus ModelRequest instant checkpoints for process streaming, and expose model field deltas only through stable structured paths such as task_dag.tasks.<task_id>.fields.<field_path> rather than raw provider token events

Anti-Patterns

• do not build a parallel action/tool dispatcher before checking Action Runtime
• do not hand-roll tool schema prompts or kwargs planners in Skills when the Agent ActionRuntime can plan against the registered action list
• do not expose core Execution Environment manager APIs as the default app-development mental model
• do not route package installation or filesystem mutation through the Python sandbox
• do not ask users to clone or editable-install DevTools when pip install agently-devtools fits
• do not make DevTools the source of truth for workflow structure
• do not present prompt-only Skills disclosure as the default execution meaning of agent.start() once the 4.1.3 route planner owns Skills candidates
• do not put route-owned Skills, Dynamic Task, or stream-composition logic directly in core when a plugin protocol can own the replaceable behavior

Read Next

• references/actions-runtime.md
• references/actions-execution-environment.md
• references/devtools.md