Agent Tools And Providers

---
name: agent-tools-and-providers
description: "Configure providers and safely operate leader-worker dispatch, text tool calls, repository tools, and literature search."
disable-model-invocation: true
metadata:
  disco-role: operating
license: Apache 2.0
---

# Agent tools and providers

Use this skill when a research project needs to configure the LLM endpoint or
when a worker must inspect files, search code, query literature, or hand an
experiment launch to monitoring. This skill describes the observable
dispatcher and tool-registry contracts; it does not run an experiment, install
source skills, or choose an execution backend.

## Quick routing

1. Confirm the provider, model, endpoint override, and credential *environment
   variable names*. Never put a secret value in a config file, prompt, report,
   or tool result.
2. Use `AgentDispatcher` for leader/worker calls and `ToolRegistry` for the
   worker's allow-listed tools. A worker has no direct filesystem, shell, or
   network access; it must emit the text protocol described in
   `references/text-tool-protocol.md`.
3. Select a worker by responsibility: `idea` for literature, `code` for
   implementation and launch, and `writing` for reports. Keep the tool set
   minimal and do not grant tools by copying another worker's list.
4. Treat the registry's returned JSON, especially `launch_experiment`'s `pid`
   and `log_file`, as authoritative. Do not replace them with numbers or paths
   guessed from model prose.
5. Before any write or command, use workspace-relative paths and the exact
   tool schemas in `references/tool-catalog.md`. Route long-running lifecycle
   and backend transport questions to the corresponding lifecycle/backend
   skills.

## Provider choices

`AgentDispatcher` supports `anthropic`, `openai`, `claude_cli`, and `codex_cli`.
The domestic aliases `deepseek`, `dashscope`, `qwen`, `moonshot`, `kimi`,
`zhipu`, and `glm` select an OpenAI-compatible endpoint while retaining the
original alias as `provider_label`. Presets, exact constructor behavior,
credential precedence, and model mapping are in
`references/provider-config.md`.

Prefer `anthropic` or `openai` for API calls and `claude_cli` when a pure text
CLI oracle is desired. `codex_cli` is suitable for leader/free-text work, but
is unsafe for authoritative worker handoff: its CLI runs its own built-in
agentic tools and cannot be forced into the registry protocol. The dispatcher
logs a warning whenever a codex worker receives tools; use another provider
for workers that write files or launch experiments.

## Dispatch contract

- `dispatch_leader(task, context)` keeps leader history within a cycle and
  parses a JSON decision. Leader history must be reset between cycles by the
  caller; the leader is not a worker tool loop.
- `dispatch_worker(agent_type, task, tool_registry)` starts a fresh worker
  conversation, appends the rendered schemas, executes parsed calls in order,
  and repeats until a response has no calls or the worker's hard `max_turns`
  limit is reached.
- Tool results are returned to the model in a new user message. A non-dict
  `args` value is converted into a structured error and is never expanded as
  keyword arguments. Unknown tools also return a structured error.
- For a code worker, a successful `launch_experiment` result is surfaced as
  `experiment_launched`, `pid`, and (when supplied) `log_file`. This result is
  the handoff consumed by monitoring.

## Safe operating rules

- A tool call is real only when it is a top-level `<tool_call>` block. Calls
  inside a triple-backtick fenced block are illustrative and are suppressed.
- Normalize paths before touching the backend. Absolute paths, empty paths,
  `..` components, and symlink escapes are rejected. Writes additionally
  protect the basenames `state.json`, `MEMORY_LOG.md`, `PROJECT_BRIEF.md`, and
  `.lock`; protected files may still be read when otherwise valid.
- `run_shell` and `launch_experiment` parse with `shlex.split` and invoke the
  backend without a shell. Empty commands, malformed quoting, and a blocked
  executable (`rm`, `sudo`, `su`, `mkfs`, `dd`, `shutdown`, `reboot`,
  `poweroff`, or `halt`) fail before execution. Do not treat this as a complete
  privilege sandbox: explicitly invoking a shell interpreter remains a
  separate capability and should be avoided.
- Repository searches are read-only, skip VCS/cache directories, skip
  symlinks and oversized/binary files, and return bounded results. Literature
  calls have network side effects and must be made only when the user permits
  them; failure is reported as JSON rather than retried blindly.

## Verification

Run the bundled `scripts/validate_provider_config.py` with representative
provider/model/override combinations. It performs no network request, does
not read credential values, and prints only normalized non-secret metadata.
For parser/security review, use synthetic fenced-call, traversal, and
semicolon-payload cases and verify that no file is created and no backend call
is made before accepting a worker handoff.

## Further reference

- `references/provider-config.md`: constructor fields, aliases, SDK/CLI paths,
  precedence, and failure behavior.
- `references/tool-catalog.md`: worker allow-lists, exact schemas, result
  shapes, bounds, protection, and literature behavior.
- `references/text-tool-protocol.md`: parsing, multi-turn result handoff,
  fenced-call suppression, and authoritative PID handling.
- `references/troubleshooting.md`: predictable configuration, parser, path,
  shell, network, and CLI failure responses.

Do not use this skill to launch training or to poll a PID. For those tasks route
to experiment lifecycle and execution/monitoring skills, respectively. For
source-skill installation or export route to skills-and-installation.