Define your agent

Make the model and execution recipe explicit, validate it locally, and keep the version used by each experiment.

An agent profile is a credential-free recipe for running an agent. It records a model selector, an exact engine version, any supplied files and setup, how the engine receives its instruction, and the outputs you require.

Use a profile when you want to repeat or compare a setup without reconstructing it from shell history. It does not contain a task environment or guarantee that the selected model is available to your account.

A profile can equip a support agent, research assistant, document analyst or other agent with its own instructions, tools and skills. The task supplies each piece of work and its environment; the assessment defines success for that work. The reviewer below is an example.

Start with a small profile

Save this as reviewer.json. The model selector and engine version are explicit; choose supported values for the environment where you will run it.

{
  "schema": "synth.agent-profile.v2",
  "agent": {
    "model": "Qwen/Qwen3.8-27B:peft:262144",
    "engine": {"type": "claude-code", "version": "2.1.263"},
    "execution": {
      "cwd": "{{task.workspace}}",
      "args": ["--model", "{{model}}", "--print"],
      "stdin": {"file": "{{task.instruction_file}}"}
    }
  }
}

This is a minimal recipe, not a qualified high-performing reviewer. Match its tools, permissions and required outputs to your task, then qualify it on representative work before using it as a baseline.

Validate it before any execution:

synth agent validate reviewer.json

Validation checks the document, references and recipe shape without logging in or running the model. It does not prove model availability, live credentials, tool compatibility or successful execution. Read any unresolved binding requirements in the result.

Give files and instructions an explicit home

The task owns the work instruction and starting files. The profile owns reusable agent behavior: additional instructions, tool configuration, hooks, skills and setup scripts. Keep a judge’s reference answer out of actor-visible files.

Profile references are substituted in execution, setup and output fields:

Reference	Meaning
{{model}}	The launch model selector. Bind it once in the engine arguments.
{{files.NAME}}	The absolute path of a named profile file.
{{task.workspace}}	The workspace supplied by the task launcher.
{{task.instruction_file}}	The file containing the task instruction.
{{run.session_id}}	The engine session identifier for this launch.
{{run.agent_dir}}	The directory where this profile’s files are prepared.
{{bindings.NAME}}	An additional binding explicitly supplied by the launcher.

A managed agent has no interactive terminal. Set one stdin source: a file for a task instruction, or fixed text for a self-contained instruction. Do not ask the managed process to inherit interactive input.

Never put account credentials or provider keys in profile files or environment values. Model access is established through the supported Synth authentication path, not by distributing secrets with a recipe.

Local execution and managed execution are different

Command	Where the recipe runs	Important boundary
synth agent validate reviewer.json	Local validation only	Does not execute the agent.
synth agent run @reviewer.json	Your machine	Not a sandbox; review scripts, tools and permissions first.
synth run start --actor @reviewer.json ...	Managed task execution	The task and launch supply the environment and bindings.
synth train start --actor @reviewer.json ...	Managed scored training	Optimizes the profile’s selected trainable model.

Use synth agent run --help for required local bindings. Do not test an untrusted setup script on your host merely because the profile passed validation.

Publish a reusable version

Local files are useful during development. Publish a profile when you want to share and reuse its immutable identity:

synth agent create acme/reviewer --profile reviewer.json
synth agent list
synth agent versions agent://acme/reviewer

Replace acme with your namespace. Copy the exact version reference from the publication receipt. An unversioned name can resolve to a different version later; pin the version for comparisons.

To update an existing name, provide its current version UUID:

synth agent create acme/reviewer \
  --profile reviewer.json \
  --expected-current-version <current-version-uuid>

This publishes a new immutable version; it does not rewrite the profile used by older runs. A stale expected version is a conflict to inspect, not a reason to overwrite someone else’s publication.

A judge is another agent role

A judge profile uses the same recipe format but performs assessment. On a run, --judge replaces the task’s default verifier. It must write a finite numeric reward to /logs/verifier/reward.json. Other fields, such as a rationale, are retained but do not contribute additional scored values.

{"reward": 0.5, "rationale": "One supported issue found; one unrelated claim rejected."}

That example illustrates the output format, not a universal grading rubric. Define what the judge should assess, what evidence it can see and how to handle unsupported findings. Design the assessment before using the reward for training.

A checkpoint changes the model, not the whole recipe

To evaluate a trained model, keep the recipe fixed and change agent.model to the full checkpoint UUID returned by synth run checkpoints. Save the changed document as a new local profile or publish a new version.

Do not silently switch tools, instructions or judges at the same time and call the result a model-only improvement. Continue with training and checkpoint comparison.