ATIF trajectory of one vis-agent run.
vis-agent --trajectory PATH writes the run as one ATIF-v1.8 document. Harbor
and its viewer read this format:
user step the prompt
agent step one for each iteration: thinking, prose, model and effort
tool call one python_execution call for each code block, with its code
observation the stdout and the error of that block
final_metrics the token and cost totals of the run
subagents one embedded trajectory for each Council child
The final agent step carries the final answer. Vis facts without an ATIF
field go to extra: iteration, block status, Activity, repairs, timeouts
and the run profile. The Activity of a block has one row for each host
function call, with its operation, arguments, result, state and duration.
Each agent step has the tokens and the cost of its provider call in
metrics. The extra of the document has the run status and evaluation,
and for a --persist run the session usage and the saved goal.
A Council child comes from its persisted turns, so its steps have the token counts and the cost of each iteration. The observation of the step that started the child refers to the child trajectory. The total cost of the run includes the cost of the children.
The CLI result has two shapes: engine keywords, or the snake_case string keys
of a --persist run through the gateway. build reads the canonical wire
shape of both.
Before the write, each known credential value becomes [REDACTED]: the
provider keys and tokens in ~/.vis/*-auth.json, in the provider
configuration and from api_key_command, the gateway token, the values of
secret settings, keychain and command values of
environment:, and values of the environment, .env and environment: whose
names contain KEY, TOKEN, SECRET, PASSWORD or CREDENTIAL. Each value also
matches in its JSON-escaped and URL-encoded forms. Credentials that their
form shows also become [REDACTED]: private PEM keys, passwords in URLs,
credential headers and well-known API key and token formats. Base64 text that
holds a known value or one of these forms becomes [REDACTED] too. Vis does not
find other secrets in the text. Only the owner can read the file.
ATIF trajectory of one `vis-agent` run. `vis-agent --trajectory PATH` writes the run as one ATIF-v1.8 document. Harbor and its viewer read this format: user step the prompt agent step one for each iteration: thinking, prose, model and effort tool call one `python_execution` call for each code block, with its `code` observation the stdout and the error of that block final_metrics the token and cost totals of the run subagents one embedded trajectory for each Council child The final agent step carries the final answer. Vis facts without an ATIF field go to `extra`: iteration, block status, Activity, repairs, timeouts and the run profile. The Activity of a block has one row for each host function call, with its operation, arguments, result, state and duration. Each agent step has the tokens and the cost of its provider call in `metrics`. The `extra` of the document has the run status and evaluation, and for a `--persist` run the session usage and the saved goal. A Council child comes from its persisted turns, so its steps have the token counts and the cost of each iteration. The observation of the step that started the child refers to the child trajectory. The total cost of the run includes the cost of the children. The CLI result has two shapes: engine keywords, or the snake_case string keys of a `--persist` run through the gateway. [[build]] reads the canonical wire shape of both. Before the write, each known credential value becomes `[REDACTED]`: the provider keys and tokens in `~/.vis/*-auth.json`, in the provider configuration and from `api_key_command`, the gateway token, the values of secret settings, keychain and command values of `environment:`, and values of the environment, `.env` and `environment:` whose names contain KEY, TOKEN, SECRET, PASSWORD or CREDENTIAL. Each value also matches in its JSON-escaped and URL-encoded forms. Credentials that their form shows also become `[REDACTED]`: private PEM keys, passwords in URLs, credential headers and well-known API key and token formats. Base64 text that holds a known value or one of these forms becomes `[REDACTED]` too. Vis does not find other secrets in the text. Only the owner can read the file.
(build result
{:keys [prompt started-at-ms profile iterations turn-position subagents
session-usage goal]})ATIF document of one finished run. result is the CLI result map. Options:
:prompt the user prompt
:started-at-ms the time when the run started
:profile the run options that shape the agent
:iterations the persisted iterations of the turn of the run. A persisted
run returns no trace, so they give its agent steps.
:turn-position the position of that turn. It gives the refs of its forms.
:subagents the Council children of the run: agent rows with their
turns, and each turn with its persisted iterations in
trace
:session-usage the usage rollup of a persisted session
:goal the saved goal of a persisted session
ATIF document of one finished run. `result` is the CLI result map. Options:
:prompt the user prompt
:started-at-ms the time when the run started
:profile the run options that shape the agent
:iterations the persisted iterations of the turn of the run. A persisted
run returns no `trace`, so they give its agent steps.
:turn-position the position of that turn. It gives the refs of its forms.
:subagents the Council children of the run: agent rows with their
`turns`, and each turn with its persisted iterations in
`trace`
:session-usage the usage rollup of a persisted session
:goal the saved goal of a persisted session(export! path result opts)Build the trajectory of one run, redact the known credentials and write it to
path. opts are the options of build.
Build the trajectory of one run, redact the known credentials and write it to `path`. `opts` are the options of [[build]].
(known-secrets {:keys [env files providers settings environment]})Credential values that a trajectory must not carry, longest first:
:env environment values whose names contain KEY, TOKEN, SECRET,
PASSWORD or CREDENTIAL
:files JSON credential files: each string under a credential key
:providers the provider configuration: each string under a credential key
:settings the values of secret settings
:environment the values that Vis gives to child processes: an
environment: value from the keychain or a command, and a
.env or environment: value under a credential name, as
[[name source value]]
Values with fewer than 8 characters do not count.
Credential values that a trajectory must not carry, longest first:
:env environment values whose names contain KEY, TOKEN, SECRET,
PASSWORD or CREDENTIAL
:files JSON credential files: each string under a credential key
:providers the provider configuration: each string under a credential key
:settings the values of secret settings
:environment the values that Vis gives to child processes: an
`environment:` value from the keychain or a command, and a
`.env` or `environment:` value under a credential name, as
`[[name source value]]`
Values with fewer than 8 characters do not count.(redact data secrets)Replace each secrets value in each string of data with [REDACTED].
Replace each `secrets` value in each string of `data` with `[REDACTED]`.
(redactor secrets)Build the function that replaces, in each string of a value, each of secrets and
each credential that its form shows with [REDACTED]. Build it once for an export.
Build the function that replaces, in each string of a value, each of `secrets` and each credential that its form shows with `[REDACTED]`. Build it once for an export.
(run-secrets)The known credentials of this process and of the bound workspace, with their forms:
also the gateway token and the provider keys that api_key_command gave.
The known credentials of this process and of the bound workspace, with their forms: also the gateway token and the provider keys that `api_key_command` gave.
(saved-json root records read-turns)(saved-json root records read-turns secrets)Encode one saved session and its children as a redacted ATIF document.
read-turns gives the turns of one session on demand. Each of secrets, by default
run-secrets, becomes [REDACTED].
Encode one saved session and its children as a redacted ATIF document. `read-turns` gives the turns of one session on demand. Each of `secrets`, by default [[run-secrets]], becomes `[REDACTED]`.
The ATIF version of each trajectory that Vis writes.
The ATIF version of each trajectory that Vis writes.
(secret-forms values)The credentials in values as an export shows them: each value of 8 characters or
more, with its JSON-escaped and URL-encoded forms.
The credentials in `values` as an export shows them: each value of 8 characters or more, with its JSON-escaped and URL-encoded forms.
(setting-secrets settings)The values of the secret settings in settings, {setting-id value}, with their forms.
The values of the secret settings in `settings`, `{setting-id value}`, with their forms.
(write! path document)Write document to path as JSON and return path. Vis writes a private
temporary file next to path, then moves it there, so only the owner can read
the trajectory.
Write `document` to `path` as JSON and return `path`. Vis writes a private temporary file next to `path`, then moves it there, so only the owner can read the trajectory.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |