rl-agent-zoo
Implement SMARTS Agent policies, AgentSpec packages, versioned zoo locators, social-agent bubbles, and optional Ray/RLlib integrations without assuming optional training dependencies are installed.
- License 许可
- MIT
- 最近更新
- 2026-09-03
- Stars
- ★ 351
- Forks
- 27
01 前言 Front Matter
- name
- rl-agent-zoo
- license
- MIT
- metadata
- { "disco-role": "operating" }
- description
- Implement SMARTS Agent policies, AgentSpec packages, versioned zoo locators, social-agent bubbles, and optional Ray/RLlib integrations without assuming optional training dependencies are installed.
- disable-model-invocation
- true
02 资源文件 6
- 参考文档references/agent-spec-and-registry.md5.5 KB
- 参考文档references/benchmark-packaging.md3.9 KB
- 参考文档references/rl-frameworks.md6.3 KB
- 参考文档references/social-agents-and-bubbles.md4.3 KB
- 参考文档references/troubleshooting.md5.7 KB
- 脚本scripts/check_agent_locator.py3.6 KB
03 SKILL.md 正文
RL and agent zoo
Use this route when a user needs a SMARTS policy object, an installable agent package, a registered locator, a social agent or bubble, or an RLlib/Ray adapter. Keep core policy and registry work separate from the simulation lifecycle route. Keep benchmark commands and full training runs reference-only.
Capability and boundary
This route covers:
smarts.core.agent.Agentpolicies and theact(obs, **configs)contract.smarts.zoo.agent_spec.AgentSpec, registry registration, dynamic module loading, andmake/make_agent.- Interface/action/observation alignment for an agent specification.
SocialAgentActor,BoidAgentActor,Bubble, airlocks, and policy kwargs.- The shape of an
RLlibHiWayEnvconfiguration and Ray worker distribution. - Safe, import-only validation of a locator with the bundled checker.
- Packaging an inference policy for a zoo or benchmark consumer.
Do not use this route for Gym reset/step/close basics or general action and
observation catalogues; use simulation-environments. Use cli-integrations
for scl zoo and scl benchmark command details. Do not promise training,
checkpoint downloads, benchmark scores, or regression results.
Fast decision path
- Decide whether the deliverable is a core Python policy, an installed zoo package, a social/bubble actor, or an RLlib integration.
- Implement and test the policy with a concrete
AgentInterface. The policy must return an action accepted by that interface's action space. - Wrap the policy and interface in an
AgentSpec; register a versioned name from an importable module. Run the locator checker before attempting a simulation. - If RLlib is requested, first probe
rayandray.rllib. They are optional, and are not installed in the prepared core environment. Do not importRLlibHiWayEnvas a core smoke test when Ray is absent. - For a benchmark deliverable, package inference code and its model/dependency
contract, then route installation and benchmark invocation to
cli-integrations.
Runtime invariants
- A policy subclasses
Agentand implementsact(self, obs, **configs).Agent.from_function(callable)is suitable for a tiny stateless policy. AgentSpec(interface=..., agent_builder=..., agent_params=...)describes both the simulator-facing interface and the policy constructor. The builder is a class or callable, not an already-built policy instance.agent_paramsare dispatched as no arguments forNone, positional arguments for a list/tuple, keyword arguments for a dict, and one argument otherwise.build_agent()raises if the builder is absent or not callable.AgentSpecis cloudpickle-checked at construction. Keep builders, params, adapters, and model handles serializable when workers will be used.- Locators use
module.importable:registered-name-vN(or-latest), where the registered name includes the version suffix. A bareregistered-name-vNworks only after that name is already registered in the current process. - A module locator causes SMARTS to import the module and expects that import
to execute
register(...). Importability is therefore part of the package contract; installing a distribution alone is not proof of registration. make(locator, **kwargs)returns anAgentSpec;make_agent(locator, **kwargs)returns(Agent, interface)and applies kwargs to the registered factory. Usemakewhen the interface/spec must be inspected first.- Do not use the deprecated observation/action/reward/info adapters for new
core code. They remain fields on the current
AgentSpecfor compatibility; RLlib's current adapter path may still exercise them, so keep any legacy use explicit and test it against the selected RLlib release.
Checks before handing off
- Confirm
AgentInterfaceand the policy's raw action agree. Check the environment's per-agentaction_space[agent_id].contains(action)rather than relying on a model's declared shape. - Confirm the policy's observation adapter output agrees with the declared model observation space, including dtype, bounds, keys, and array shape.
- Import the package module and run
scripts/check_agent_locator.py --locator module:agent-name-v0. The checker only imports and inspects the registry; it never installs, constructs a model, trains, downloads a checkpoint, or starts a simulator. - Build the
AgentSpecand policy without a scenario first. Use a bounded simulation smoke only when a scenario is supplied and the lifecycle route owns that smoke. - For Ray, validate worker configuration and serialization before attempting
any long run. The optional framework status is
unverifieduntil the user supplies a compatible installed stack.
Progressive references
- AgentSpec and registry — exact interfaces, locator grammar, registration and construction patterns.
- RL frameworks — RLlibHiWayEnv, Ray workers, spaces, optional Torch/TensorFlow, and resume caveats.
- Social agents and bubbles — actor, boid, bubble, airlock, travel, and policy-kwargs rules.
- Benchmark packaging — inference package layout, dependency/model contracts, and benchmark compatibility gates.
- Troubleshooting — installation/import, optional dependencies, config/data, API/CLI mistakes, and workflow failures.
04 同仓库更多 Skills
passnet-triton-opt
Make a single PassNet Triton kernel fast AND numerically faithful: performance model (when a replacement can win at all), block/grid/warp tuning, autotune policy, launch overhead, and per-op numeric recipes to pass the dtype baseline tolerances. Use when a pass matches and is correct but speedup below expected, or when correctness fails by small numeric margins.
passnet-solve
END-TO-END playbook for solving one PassNet sample: analyze the computation graphs, decide the optimization strategy (what to fuse, what to replace, what to leave alone), drive the iteration loop, and maximize the sample score. This is the ENTRY skill — invoke it first for any PassNet optimization task; it tells you when to use passnet-pattern-fusion, passnet-triton-opt and passnet-feedback.
passnet-skill
PassNet GPU kernel optimization via compiler passes. Design and implement Triton-based optimization passes, create pass files under ./pass_dir/, self-evaluate with pass_evaluator, and iterate to maximize GPU speedup.
passnet-pattern-fusion
Author PassNet pass files: write patterns that actually MATCH the FX graph, pick fusion regions (which ops to absorb into one Triton kernel), and structure multi-pass submissions with the mandatory shared-dispatch architecture. Use when creating or fixing pattern()/replacement_args()/replacement_func() files, when a pass "failed to match", or when deciding how to fuse multiple kernels/ops.
passnet-orchestrate
Round/batch planning and decision support for PassNet graph optimization. Use for multi-sample triage, worker allocation, eval-budget policy, and post-eval keep/revert decisions. For solving one concrete sample end to end, use passnet-solve as the entry skill; consult this skill only when you need broader planning or a specific decision gate.
passnet-feedback
Fast, deterministic feedback for PassNet work: pre-flight pattern/match verification WITHOUT burning a GPU evaluation, per-node bottleneck analysis of a sample's graphs, and eval-log parsing into per-variant status + estimated score + failure classification. Use BEFORE every GPU evaluation (check_pattern), at the START of a sample (analyze_graph), and AFTER every evaluation (parse_eval_log).