Agent

The agent command passes off a multi-step orchestration task to an AI agent, so you can describe a goal in natural language instead of driving the CLI yourself.

Agent settings are read from the [agent] section of trilogy.toml - provider, model, api_key_env, max_iterations, tool_output_limit, and quiet. See trilogy.toml Configuration.

Requires pytrilogy[ai] extras.

Usage

trilogy agent <command> [options]

Arguments

Argument	Description
command	The task to hand off, in natural language.

Options

Option	Description
-c, --context TEXT	Additional context file for the agent. One path per flag.
-m, --model TEXT	AI model to use. Overrides trilogy.toml.
-p, --provider TEXT	LLM provider: anthropic, openai, google, or openrouter. Overrides trilogy.toml.
-e, --env TEXT	Set env vars as KEY=VALUE, or pass an env file path.
-l, --log-file FILE	Append every LLM response and tool call/result as JSONL to this file.
-i, --interactive	After the agent returns control, prompt for the next command.
--quiet / --no-quiet	Drop the show_message tool to cut conversation churn. Overrides [agent].quiet.
--toolset [trilogy|sql]	Tool surface. trilogy (default) uses the Trilogy CLI; sql is the no-Trilogy baseline.

How It Works

The agent drives a tool loop over show_message, trilogy, todo, and return_control_to_user. With the default trilogy toolset it works by calling the Trilogy CLI, so anything you can do from the command line is available to it. The sql toolset swaps that for plain file read/write plus raw SQL execution, and exists mainly as a baseline for comparison.

Full Examples

# Analyze and create a dashboard
trilogy agent "analyze sales trends and create a dashboard"

# Ingest and validate new data
trilogy agent -i "ingest new data and run validation tests"

# With additional context
trilogy agent "create ETL pipeline" -c existing_models/README.md -c requirements.txt

# Pin the provider and model for one run
trilogy agent "optimize query performance for customer reports" -p anthropic -m claude-sonnet-5

# Capture a full trace for debugging
trilogy agent "refactor the data model" --log-file agent_run.jsonl

Notes

• Requires an API key in the environment variable named by [agent].api_key_env
• --interactive keeps the session alive so you can chain follow-up instructions
• --log-file is the best way to see exactly what the agent did and why
• Context files help the agent understand your project conventions