Creating an Agent

Creating an Agent

Define an agent by providing a name, a system prompt with clear instructions, a list of tools, and a model to use.

System Prompt

The system prompt is the most important input. It defines the agent’s role, tone, capabilities, and constraints. Be specific and explicit about what the agent should and should not do.

Choosing a Model

Select a model based on the complexity of your task. Larger models handle multi-step reasoning better; smaller, faster models suit simpler, higher-frequency tasks.

Running the Agent

Once configured, call agent.run() with the user’s input. The agent handles the loop automatically and returns a structured result when done.

The queue.yaml config file

Agents are defined in a queue.yaml file at the root of your project. This file describes the agent’s name, model, system prompt, tools, and execution policies. It is checked into your repo like any other config file.

Minimal config

name: refactor-agent model: claude-3-7-sonnet system_prompt: | You are a senior TypeScript engineer. Your job is to refactor code to be cleaner, more idiomatic, and better tested. Always explain your reasoning before making changes. tools: - read_file - write_file - run_tests

Naming your agent

Give your agent a specific, descriptive name. The name is visible in the dashboard, appears in trace logs, and is used to reference the agent from the CLI and API. Use kebab-case by convention.

Writing the system prompt

The system prompt is your most powerful lever. A good prompt includes: the agent’s role and expertise, the scope of what it should touch, explicit constraints (what it must never do), the expected output format, and how to handle ambiguity.

Keep prompts specific. “You are a helpful assistant” is almost always worse than “You are a TypeScript engineer focused on the payments module. You never modify files outside src/payments/. When in doubt, ask.”

Choosing tools

Only give your agent the tools it actually needs. Fewer tools reduce the surface area for mistakes, make the agent more predictable, and help the model focus. Add tools incrementally as you discover what the agent needs.

Execution limits

Set max_steps and timeout_seconds in your config to bound run duration. Queue will halt the agent gracefully if either limit is reached, returning whatever it has completed so far along with a stop reason.

max_steps: 25 timeout_seconds: 300

Testing your agent

Use queue run --dry-run to simulate a run without committing any file changes or triggering integrations. This lets you check reasoning and tool selection without side effects.

You can also write eval suites — sets of test goals with expected outcomes — and run them automatically in CI with queue eval.