Using Falcon with an Agent

Most people don't need to memorize Falcon's CLI. Install the falcon-workflow skill and let your agent (Claude Code or Codex) drive Falcon for you in plain language — submit experiments, capture profiles, run analyses, and read the results back. The agent picks the right falcon workflow commands, waits for jobs to finish, and summarizes the output, so you stay in natural language end to end.

You only describe the goal. The agent chooses the right command, fills in the flags, waits for each job to reach a terminal state, and reads the results back to you in plain language — you never have to remember the CLI surface or poll a job yourself.

Why use an agent

• No command memorization — describe what you want; the agent maps it to the right Falcon command.
• The agent picks the right command — it chooses the correct falcon workflow verb and flags for the task.
• It waits and reads results for you — the agent blocks on the terminal state and reports back, instead of you polling.
• Good for multi-step tasks — chains like submit → wait → analyze run as one request.

Setup

1. Install and authenticate the Falcon CLI. The skill drives the same falcon binary you'd run by hand, so it must be installed and logged in first. Follow the Prerequisites in Getting Started, then run falcon auth login. The agent reuses these same credentials.

2. Install the skill. falcon-workflow is distributed as a Claude Code plugin marketplace; Codex installs from the same source directory.

   • Claude Code — add the Falcon repo as a plugin marketplace once, then install the falcon-workflow plugin:

     /plugins
     # Add Marketplace: git@github.com:primatrix/Falcon.git
     # Install plugin: falcon-workflow

   • Codex — sync the skill from a cloned Falcon repo:

     # from a cloned Falcon repo
     rsync -a --delete skills/falcon-workflow/ ~/.codex/skills/falcon-workflow/

3. That's it — the skill is ready to use. The agent reads the skill's SKILL.md frontmatter and invokes it automatically when a request matches; you don't trigger it by hand.

Example interactions

Each example below is a short end-to-end script: what you say in plain language, what the agent does behind the scenes, and what you get back. The exact falcon workflow command sequence is tucked into the collapsible "Under the hood" block — you never type it yourself.

Run a training experiment end to end

You:

Submit the training run in exp.yaml and tell me when it finishes.

The agent:

• submits the experiment and captures its exp_id
• waits for it to reach a terminal state (SUCCEEDED / FAILED)
• if it fails, pulls the logs and explains why

You get back:

✅ exp-7f3a… succeeded in 8m12s. Artifact at gs://…/artifacts/art-…/. Want me to run an analyzer on it?

Under the hood

falcon workflow exp submit -f exp.yaml      # → ids.exp_id
falcon workflow exp wait <exp_id>           # blocks until SUCCEEDED/FAILED
falcon exp logs <exp_id>                    # only if it failed

The agent branches on ids.status (not just ok) — a *_wait that returns a terminal FAILED still reports ok=true.

Profile a workload and summarize bottlenecks

You:

Profile the sglang-jax serving workload in profile.yaml and tell me where the time goes.

The agent:

• submits the profiling run and captures its exp_id
• collects the profile artifact once the run finishes
• enrolls the xprof-summary analyzer on the artifact
• reads the generated report and summarizes the hotspots

You get back:

✅ Profile collected and analyzed. Top cost is attention (~38% of step time), then the MoE all-to-all. Full breakdown is in the analyzer's report.md — want me to paste the table?

Under the hood

falcon workflow profile submit -f profile.yaml   # → ids.exp_id
falcon workflow profile collect <exp_id>          # → uris.artifact_uri
# analysis.yaml: spec.name xprof-summary, plugin_names [xprof-summary],
#   params { profile_format: auto, workload_kind: serving }
falcon workflow analysis create -f analysis.yaml  # → ids.analysis_id
falcon workflow analysis wait    <analysis_id>    # blocks until terminal
falcon workflow analysis outputs <analysis_id>    # → data.outputs[]
falcon workflow analysis cat     <analysis_id> report.md   # → data.content

The agent bases its summary only on the analyzer's declared outputs (report.md, summary.json), never on raw bucket reads.

Compare two runs for precision drift

You:

Compare the dumps from exp-A and exp-B and tell me if the numerics drifted.

The agent:

• builds a multi-artifact comparison over both experiments' artifacts
• runs the precision-compare analyzer in a single pass
• waits for it to finish and reads the comparison report back

You get back:

✅ Compared exp-A vs exp-B. Layer norms and attention match within tolerance; the MoE router logits diverge after layer 18 (max rel. error 3e-2). Looks like a real drift, not noise — details in report.md.

Under the hood

# compare.yaml: inputs[] are generic (name + role + exp_id), plugins
#   includes precision-compare
falcon workflow analysis compare -f compare.yaml   # → ids.analysis_id
falcon workflow analysis wait    <analysis_id>     # blocks until terminal
falcon workflow analysis outputs <analysis_id>     # → data.outputs[]
falcon workflow analysis cat     <analysis_id> report.md   # → data.content

If an input artifact isn't SUCCEEDED, the wrapper fails with a precondition error that names the offending input.

Figure out why a run is stuck

You:

My experiment exp-… has been pending forever. What's wrong?

The agent:

• pulls the experiment's status and job conditions
• reads the latest condition to identify the stage it's stuck at
• falls back to the pod logs only if the conditions don't explain it
• translates the diagnostic into plain language

You get back:

The run is stuck at scheduling: condition ResourceProvisioning with reason ClusterBusy — the cluster is retrying because the reservation is full right now, not a bug in your manifest. It'll start once capacity frees up; want me to keep watching it?

Under the hood

falcon exp get  <exp_id>    # → data.job, data.conditions[] (Scheduled →
                            #   ResourceProvisioning → ResourceReady → …)
falcon exp logs <exp_id>    # only if conditions don't explain the stall

The agent reads data.job first for the concise diagnostic, then data.conditions[] for the stage (e.g. ClusterBusy retry, Unschedulable), before ever touching logs.

Poke at a running experiment

You:

Run nvidia-smi inside the running pod for exp-…, and grab /tmp/output.log while you're there.

The agent:

• execs the command in the running experiment's pod
• copies the requested file back to your machine
• reports the command output and the transfer result

You get back:

Here's nvidia-smi from rank 0 (all 8 devices busy, ~71% util), and I pulled /tmp/output.log to ./output.log (2.3 MB).

Under the hood

falcon exp exec <exp_id> --rank 0 -- nvidia-smi   # runs in the live pod
falcon exp cp   <exp_id>:/tmp/output.log ./output.log   # file transfer

These need a RUNNING experiment with the injected Falcon agent; for a pending or terminal run the agent inspects exp get / exp wait conditions and exp logs instead.

What the agent does under the hood

The agent composes falcon workflow ... commands and parses their stable v1 JSON envelope; the command set and envelope contract are defined in the skill itself. See the skill source at skills/plugins/falcon-workflow.

When to use the CLI directly

Prefer the bare falcon CLI for scripting and CI, quick one-off actions, or when you want fine-grained control over flags and output. See Getting Started and the Experiment Lifecycle.