Skip to content

Run configured agents from Python or the command line

Crystal Lattice can run a configured agent without starting the interactive terminal or HTTP server. A run creates or continues an ordinary persisted session by default, or executes one non-retained turn when requested. Both modes report bounded progress and return the final result directly.

Use this workflow for scripts, local automation, parallel investigations, and follow-up prompts whose sessions should remain visible in other Crystal Lattice frontends.

Prerequisites

Use the supported bundled-Python command or a source checkout, and configure at least one agent:

crystal-lattice agents

The command prints one configured agent ID per line:

claude-openrouter
codex-openai

Use --format json for machine-readable discovery:

crystal-lattice agents --format json
{"agents":["claude-openrouter","codex-openai"]}

Add --details to inspect safe effective defaults and configurable fields without making a provider request:

crystal-lattice agents --details --format json

Python callers use runtime.list_agent_descriptors() or runtime.describe_agent(agent_id). Descriptors contain display metadata, the provider route and plugin, safe effective model/reasoning values, and the flattened plugin config schema. They do not contain credentials.

Global options precede the standalone command. For example:

crystal-lattice \
  --config ~/.crystal/config.json \
  --sessions-dir ./.crystal/sessions \
  agents

Discover available models

Select a configured agent to discover models through its provider, extensions, and features:

crystal-lattice models --agent codex-openai --format json

JSON preserves complete plugin-provided descriptors and their order:

{
  "agent_id": "codex-openai",
  "models": [
    {
      "id": "gpt-6-luna",
      "name": "GPT-6-Luna",
      "description": "Fast and affordable model for easier tasks."
    }
  ]
}

Each descriptor has a non-empty id. name, description, and additional metadata depend on the plugins. The example shows one possible catalog entry; the command returns the selected agent's discovered catalog.

The default text format prints tab-separated ID, name, and description, with one model per line and empty columns for absent display fields. Tabs and newlines inside fields become spaces. For example:

crystal-lattice models --agent codex-openai | grep -i luna

Python callers use the same discovery path:

from agent_terminal_app import open_runtime

with open_runtime() as runtime:
    models = runtime.list_models(agent_id="codex-openai")
    for model in models:
        print(model["id"], model.get("description", ""))

Discovery uses the agent's effective configured defaults and the existing model cache. Plugins may fetch catalogs internally. The call does not create a session or send an inference request. An empty tuple in Python, or "models": [] in JSON, follows the existing plugin contract when no models are returned; it does not prove that the provider cannot run a manually specified model.

Discover runtime and plugin capabilities

Treat the active runtime as authoritative before reading implementation documentation:

  1. Use agents --details --format json to inspect the selected agent's safe effective defaults and flattened provider/plugin configuration schema.
  2. Use models --agent ID --format json for the model catalog. In the interactive terminal, use /action to list applicable action-oriented UI elements; a one-shot headless action discovery/execution command is not yet available.
  3. If those runtime descriptors do not explain a field or behavior, read the owning plugin's README and package documentation under the runtime-provided BUILTIN_PLUGINS directory. Inspect plugin source there only when the documentation and descriptors leave an implementation detail unresolved.

The opt-in external-project guidance renders the active built-in plugin path as Built-in plugin docs and source. This path follows the selected source, archive, or installed runtime rather than assuming a repository checkout. General application documentation remains available through CRYSTAL_LATTICE_DOCS and CRYSTAL_LATTICE_DOCS_URL.

Application actions and UI schemas are already available to frontends through the HTTP API. Adding equivalent one-shot CLI and LocalAgentRuntime discovery and execution is a separate follow-up; agents should not infer that every plugin procedure is currently callable through the headless commands.

Python first run

The public local API is provided by the crystal-lattice-cli distribution's agent_terminal_app module:

from agent_terminal_app import RunProgress, open_runtime


def report(progress: RunProgress) -> None:
    print(progress.message)


with open_runtime() as runtime:
    result = runtime.run(
        "Inspect this project's test strategy.",
        agent_id="claude-openrouter",
        on_progress=report,
    )

print(result.status)
print(result.session_id)
print(result.output_text)

open_runtime() searches for configuration in this order:

  1. ./.crystal/config.json;
  2. ~/.crystal/config.json.

Unlike the CLI, the Python helper does not create a missing configuration. Pass config_path and session_root when the defaults are not appropriate:

from agent_terminal_app import open_runtime


with open_runtime(
    config_path="/workspace/.crystal/config.json",
    session_root="/workspace/.crystal/sessions",
) as runtime:
    result = runtime.run("Review README.md.", agent_id="codex-openai")

The runtime loads dotenv values using the same config, project, user, and working-directory precedence as the command. Existing process-environment values continue to win.

Always close the runtime, preferably with with. It owns plugin processes, the application async runtime, environment overlays, event state, and its notification and snapshot-selection adapters.

Results

runtime.run(...) returns AgentRunResult:

result.status          # succeeded, failed, cancelled, or interrupted
result.session_id      # persisted session or ephemeral correlation identity
result.request_id      # request cancellation and diagnostic identity
result.agent_id        # configured agent used by the session
result.persistence     # persisted or ephemeral
result.output_text     # final assistant text
result.final_messages  # final response messages
result.error           # bounded RunError or None

The result intentionally does not contain the complete serialized session. Earlier messages, provider-native state, and long tool output therefore do not enter a calling script merely because it needs the final answer.

An error contains a stable category and bounded message without a traceback or complete provider response. Use configured logs or the lower-level event API when deeper diagnostics are necessary.

Request-scoped settings

Python callers pass provider/plugin settings through overrides:

result = runtime.run(
    "Inspect the project.",
    agent_id="codex-openai",
    overrides={
        "model": "gpt-5.6-luna",
        "reasoning_effort": "high",
    },
)

Use runtime.describe_agent(...) to discover the selected agent's flattened config schema. Overrides apply only to that request and do not mutate the source config or a persisted session's stored settings.

Progress

Pass on_progress to observe request and tool activity:

def report(progress: RunProgress) -> None:
    tool = f" [{progress.tool_name}]" if progress.tool_name else ""
    print(f"{progress.kind}{tool}: {progress.message}")


with open_runtime() as runtime:
    result = runtime.run(
        "Run the relevant tests and summarize failures.",
        agent_id="codex-openai",
        on_progress=report,
    )

Progress records are ordered and bounded. They can identify request, assistant, and tool phases, but they do not carry complete tool results, provider-native payloads, tool arguments, or multipart bodies.

The callback runs synchronously and should return promptly. If it raises, Crystal Lattice requests cancellation, completes request cleanup, and re-raises the callback exception.

Raw public events remain available from the lower-level AgentApplication API for applications that need the complete event contract.

Follow up in the same session

Use the first result's session_id:

with open_runtime() as runtime:
    first = runtime.run(
        "Compare the two provider adapters.",
        agent_id="claude-openrouter",
    )
    follow_up = runtime.run(
        "Focus only on cancellation behavior.",
        session_id=first.session_id,
    )

print(follow_up.output_text)

The follow-up uses the persisted conversation and the agent already attached to the session. It does not silently switch agents.

Message append and request admission are one operation. If the session already has an active request in this application process, the follow-up is rejected and its proposed message is not appended.

Resend after a recoverable failure

Retry the current persisted history without appending another user message:

crystal-lattice run --session SESSION_ID --resend

Python callers use runtime.resend(session_id). Resend is intended for recoverable provider failures or a tool-loop limit after completed tool results have already been saved. It starts a new request from the exact persisted conversation; it does not duplicate the last user prompt. Resend is available only for persisted sessions and cannot be combined with --agent, another prompt source, or --ephemeral.

Non-retained runs

Use an ephemeral run when one answer is needed and no child session should remain visible in Crystal Lattice:

with open_runtime() as runtime:
    result = runtime.run(
        "Inspect these files and return a concise finding.",
        agent_id="codex-openai",
        persistence="ephemeral",
    )

The request uses the same configured agent, tool loop, progress, timeout, cancellation, and result contracts. Session checkpoints remain in memory and no canonical session file is written. result.session_id is a request-scoped correlation identity, not a reusable persisted session. Ephemeral runs cannot be continued by session_id.

Operational logs and separately configured provider usage/cost stores are not session storage and may still retain their normal bounded records.

Parallel Python runs

Use normal Python futures for distinct sessions:

from concurrent.futures import ThreadPoolExecutor

from agent_terminal_app import open_runtime


assignments = [
    ("Inspect provider behavior.", "claude-openrouter"),
    ("Inspect CLI behavior.", "codex-openai"),
]

with open_runtime() as runtime:
    with ThreadPoolExecutor(max_workers=len(assignments)) as executor:
        futures = [
            executor.submit(runtime.run, task, agent_id=agent)
            for task, agent in assignments
        ]
        results = [future.result() for future in futures]

One runtime can run distinct sessions from different threads. Do not submit concurrent calls to the same session.

Compact history

Load a bounded view without full tool output:

with open_runtime() as runtime:
    history = runtime.history(
        result.session_id,
        start=-50,
        roles={"user", "assistant", "tool"},
    )

for item in history.messages:
    print(item.index, item.role, item.content)

Compact rows contain:

  • the canonical message index and role;
  • bounded whitespace-normalized content;
  • the canonical text length;
  • explicit truncated and omitted flags;
  • small tool identifiers and status when available.

Tool messages prefer a plugin-provided metadata.display.single_line summary. They otherwise use a bounded deterministic fallback. Provider-native history, unrestricted metadata, multipart content, and binary data are excluded.

Default bounds retain at most the newest 100 selected messages, at most 500 content characters per row, and at most 20,000 content characters overall. Range selection happens before role filtering. Content budgets are allocated from newest to oldest, and retained rows are returned in chronological order.

Retrieve one canonical message explicitly when its complete content is needed:

full = runtime.get_message(result.session_id, index=7)
print(full["message"]["content"])

Negative indices use Python indexing. A full message may contain long or sensitive tool, metadata, or multipart fields; request it only when needed.

Neither operation modifies session history.

For complete ranges with caller-selected fields, plugin-filtered session enumeration, and JSON/text shell pipelines, see Query sessions and messages.

Command-line runs

Run one task:

crystal-lattice run \
  --agent codex-openai \
  --prompt "Inspect the package tests."

Inspect agent defaults, apply request-scoped settings, and avoid retaining a session:

crystal-lattice agents --details --format json
crystal-lattice run \
  --agent codex-openai \
  --set model=gpt-5.6-luna \
  --set reasoning_effort=high \
  --ephemeral \
  --prompt-file investigation.md \
  --format json

--set may be repeated. JSON values such as true, 42, arrays, and objects are decoded; other values remain strings. Settings use the same generic config keys exposed by the selected agent's schema.

For multiline or sensitive input, prefer a file or stdin over a shell argument:

crystal-lattice run \
  --agent codex-openai \
  --prompt-file investigation.md
crystal-lattice run \
  --agent codex-openai \
  --stdin < investigation.md

Exactly one of --agent and --session, and exactly one of --prompt, --prompt-file, and --stdin, is required.

The opt-in agent guidance also calls out these multiline forms so a parent agent does not need to discover shell quoting limits through trial and error.

Continue a completed session:

crystal-lattice run \
  --session "<session-id>" \
  --prompt "Now verify the documentation."

Text mode prints only final assistant text to stdout. Progress and the session/request identity go to stderr. An ephemeral text run labels the identity as request-scoped and does not advertise it for follow-up.

JSON output

Use JSON for orchestration:

crystal-lattice run \
  --agent codex-openai \
  --prompt-file investigation.md \
  --format json \
  > result.json \
  2> progress.log

Stdout contains exactly one JSON document:

{
  "status": "succeeded",
  "session_id": "<session-id>",
  "request_id": "<request-id>",
  "agent_id": "codex-openai",
  "persistence": "persisted",
  "output_text": "<assistant response>",
  "final_messages": [
    {
      "role": "assistant",
      "content": "<assistant response>"
    }
  ],
  "error": null
}

Application logs, startup output, and progress are kept away from stdout. --no-progress suppresses ordinary progress but not errors.

Command-line history

Inspect compact history:

crystal-lattice history \
  --session "<session-id>" \
  --start -50

Filter roles and use JSON:

crystal-lattice history \
  --session "<session-id>" \
  --start -50 \
  --role user \
  --role assistant \
  --format json

Retrieve one full message:

crystal-lattice history \
  --session "<session-id>" \
  --index 7 \
  --format json

--index cannot be combined with range or role options.

Parallel shell runs

Use ordinary shell process control and distinct sessions:

crystal-lattice run --agent codex-openai --prompt-file code.md \
  --format json > code.json 2> code.progress &
code_pid=$!

crystal-lattice run --agent claude-openrouter --prompt-file docs.md \
  --format json > docs.json 2> docs.progress &
docs_pid=$!

wait "$code_pid" "$docs_pid"

The direct commands do not provide cross-process same-session locking. Do not use separate CLI processes as simultaneous writers to one session. Use a distinct session for each parallel assignment.

Let a configured agent delegate from another project

Newly generated default configurations include an optional system-message section that tells an agent how to use this exact Crystal Lattice runtime from the current project, even when that project was not launched by Crystal Lattice.

Enable it for one session:

/set include_crystal_lattice_access true

Mobile and desktop session settings expose the access checkbox through the normal configuration schema. The setting defaults to off and is independent from Include TASKS Guidance.

Source checkouts and bundled-Python distributions show Include Crystal Lattice Access Guidance. When enabled, the agent receives:

  • an authoritative CLI argument vector rendered as a correctly quoted command;
  • the active --config and --sessions-dir, so delegated calls cannot select an unrelated project config or session store;
  • examples for agent discovery, initial runs, completed-session follow-ups, compact history, session enumeration, and projected canonical messages;
  • the applicable Python interpreter and from agent_terminal_app import open_runtime when a general Python runtime is available;
  • local application documentation when included in the runtime and the public documentation URL.

Optimized frozen executables show Include Crystal Lattice Access Guidance (CLI only). Their separately authored section includes CLI and documentation instructions, explicitly says that no supported general Python SDK is available, and never emits an SDK import or interpreter claim.

If the CLI/config/session/documentation values are absent or invalid, the setting remains visible as Include Crystal Lattice Access Guidance (unavailable). It is disabled and its description names the missing or invalid values. A previously stored true override cannot compile either section in that state.

The config owns a separate parent-only delegation section after the access mechanics. It tells the parent agent that a child receives the selected agent's own configured system/developer message while the parent supplies a self-contained child user prompt. The parent is told not to copy its system message, hidden reasoning, or transcript into that prompt. It also explains request-scoped settings, persisted follow-ups, and non-retained one-shot runs.

The guidance does not turn ordinary runs into parent-linked persistent subagents and does not add mid-run input, detached lifetime, or restart recovery.

Adopt the section in an existing config

Crystal Lattice does not rewrite an existing user or project config. Add both placeholders at the end of the applicable system_message.template:

{{CRYSTAL_LATTICE_ACCESS}}

{{CRYSTAL_LATTICE_CLI_ACCESS}}

Copy the bundled default config's mixins.crystal_lattice_access definition and its system_messages/helpers/crystal_lattice_access.py file into the corresponding active config directory, then add "crystal_lattice_access" as the last mixin_refs entry for the agent. That one mixin contains the complete inspectable Markdown for both access variants and the separate parent-only delegation section, plus the named runtime-value placeholders and conditions.

The runtime owns CRYSTAL_LATTICE_SYSTEM_MESSAGES in the same way it owns BUILTIN_PLUGINS. The helper contributes availability, conditions, and the session checkbox; the configuration owns every line of agent guidance.

The other runtime-owned values are:

  • BUILTIN_PLUGINS, the active built-in plugin source, README, and package documentation root;
  • CRYSTAL_LATTICE_CLI_ARGV_JSON;
  • CRYSTAL_LATTICE_CLI_COMMAND;
  • CRYSTAL_LATTICE_CONFIG;
  • CRYSTAL_LATTICE_SESSIONS;
  • CRYSTAL_LATTICE_PYTHON when available;
  • CRYSTAL_LATTICE_PYTHON_API_MODULE when available;
  • CRYSTAL_LATTICE_DOCS when local docs are available;
  • CRYSTAL_LATTICE_DOCS_URL.

These values describe runtime locations only. They do not expose provider credentials, auth state, plugin-cache contents, or arbitrary environment variables.

Cancellation, timeout, and exit codes

Set a positive finite timeout:

crystal-lattice run \
  --agent codex-openai \
  --prompt-file investigation.md \
  --timeout 600

Ctrl-C requests cancellation and exits with interrupt status. Cancellation is cooperative: a provider or tool that is blocked in an operation without cancellation support may finish that operation first.

Exit code Meaning
0 Command or agent run succeeded
1 Agent/application failure or interrupted run
2 Invalid input, configuration, agent, session, or message index
124 Timeout-triggered cancellation
130 User interrupt

Failed and cancelled runs still produce a structured JSON result when request execution progressed far enough to create one. Failures before a request result exists leave JSON stdout empty and write diagnostics to stderr.

Persistence and security

Persisted runs use ordinary filesystem sessions. They remain available to terminal, HTTP, mobile, and desktop frontends that use the same session root. Ephemeral runs do not write a canonical session and cannot be resumed after the call returns.

Direct execution loads provider credentials and tools from the selected configuration. Apply the same trust and plugin-policy rules as an interactive run. Compact history limits transfer but is not an authorization boundary. Full-message retrieval can expose everything intentionally stored on that message.

The local API and command do not start a network listener.

Troubleshooting

Crystal Lattice config not found : Create ./.crystal/config.json or ~/.crystal/config.json, or pass config_path in Python. The CLI can create its normal default configuration through its existing config options.

Unknown agent_id : Run crystal-lattice agents and use one of the returned IDs.

Session ... not found : Verify --sessions-dir or the Python session_root. A session ID is scoped to that store.

Session ... already has active request : Wait for the current in-process request to finish. The rejected message was not appended.

No immediate cancellation : The active provider or tool may be inside a blocking operation that does not yet observe cooperative cancellation.