Working with the agent

The concepts page covers what the agent is. This is about getting good work out of it.

Ask for outcomes, not keystrokes

The agent is better at "what" than "exactly how." Tell it the result you want:

"Find the columns most correlated with churned and show the top ten."

That beats spelling out df.corr(), sort, .head(10). It lets the agent handle the edge cases (non-numeric columns, NaNs) without you listing them. Save the precise instructions for when the details actually matter to you.

Give it the context it needs

The agent acts on what it knows. If a result depends on something specific, like which column is the target, what "recent" means, the units, or which file you mean when there are several, say so up front. When it has to guess, it'll either ask or pick a default, and telling it early saves a round-trip.

Reading the chat

The agent's work comes through as cards rather than one wall of prose: a plan, a thinking block, a suggestion, a tool call, a clarification, research results, a sub-agent, and the deliverables strip at the tail of the turn. Each one is described in The agent.

The strip is the one worth knowing about early, because it answers "where did the thing it just made go". It lists what the turn produced (a cell, a file, a research run, a worker trace) and each row opens it. The same items collect in the Deliverables section of the sidebar's Files tab, alongside Workspace, Notebooks and Datasets, so you can find them again after the chat has scrolled on.

Stepping in

You don't have to wait for the agent to finish. What happens to a message you send mid-run depends on what it carries and how you send it:

• Enter, plain text. The message is handed to the turn already running. The agent reads it at its next step and folds it in. Nothing restarts, nothing is thrown away.
• Enter, with an attachment or an @-reference. Those are resolved when a turn starts, so they can't join one already in flight. The message parks in a small queue above the input and goes out on its own when the turn ends. You can drag to reorder the queue, remove an entry, or hit Send now to interrupt with it immediately.
• ⌘Enter (Ctrl+Enter). Stops the current run first, then sends. This is the only keyboard gesture that interrupts. Use it when you'd rather cut the run than steer it.

The stop button halts the run without sending anything.

The same message, sent at the same moment into a turn that is already running: plain Enter is absorbed by the turn in flight, a message carrying an attachment or an @-reference waits in the queue until that turn ends, and ⌘/Ctrl+Enter stops the turn so a new one can start.

You can also edit a cell yourself and the agent continues from your version. Skip a suggestion and it drops it, and since it remembers what you do with its suggestions, skipping the same kind repeatedly trains it to stop offering them.

When something goes wrong

If a cell errors, the agent usually reads the traceback and tries a fix on its own. If it loops or heads the wrong way, stop it and be specific about what's off. "The error is a dtype mismatch on the join key" gets a fix faster than "that didn't work."

Point at things with @

Type @ in the input to reference something specific instead of describing it: a cell, a dataset, the current plan, or a paper the agent found on a research run. A popup filters as you type, and the reference travels with your message, so "fix the join in @cell 12" is unambiguous where "fix the join in that cell above" isn't.

One trade-off worth knowing: an @-reference is resolved when a turn starts, so a message carrying one can't steer a turn that's already running. It queues instead, as above.

Attach files for context

You can attach a file to a chat message, like a data dictionary, a spec, or a sample, so the agent has it while it works. Common data and document formats work: CSV, JSON, Excel, Parquet, text and Markdown, PDF, Python files, notebooks, and images. For datasets you'll actually load and run against, upload them to the workspace instead, so the code reads the real file.

Match the model to the task

A quick reformat doesn't need a frontier model, but designing an approach might. You can change the model and reasoning effort per message, so it's worth matching them to the work, both for quality and for cost.

If you already pay a provider, you can run the agent on that instead: paste an API key to use your own key, or pair your machine to run turns through your own Claude Code or Codex CLI with the local runner.