Skip to content

Studio agent quick guide

AlexPearce3D Studio has three agent entry points. They share the same typed Comp operations, but they have different setup and availability.

Studio Operator and Command K

  1. Open the intended project and Comp workspace.
  2. Select the node you want to discuss. For a frame question, move the playhead to the exact frame first.
  3. Ask in Studio Operator, or press Command K and type the instruction.
  4. If Studio has prepared viewport evidence, review the thumbnails and labels. Choose Share, Ask Without Images, or Cancel.
  5. Read the result and inspect the graph. Each accepted graph edit is one native, Undoable transaction.

Useful prompts include:

  • “What is wrong with frame 68?”
  • “Why is this node clipping the highlights?”
  • “Does this branch introduce a color shift?”
  • “Compare the current frame before and after this node.”

Use Add Image or Paste Image to include a screenshot with only the current question. Studio does not continuously stream the viewport or automatically add screenshots to the project.

For a request such as “replace the woman on the right with a realistic robot,” Studio first proposes the visible subject against the exact current-frame image. Choose Confirm Subject & Find Matches only when the description and frame are correct. Studio then opens the existing Subject Track review: accept the intended local SAM proposal, review its seed, and choose Track Shot Bidirectionally. Proposal acceptance does not start tracking. This confirmation does not create a mask or track from a model-drawn box and does not upload media or start Seedance.

When visual capture is unavailable, Studio still sends the current graph, selection and playhead metadata. The answer should explicitly say that it cannot see the frame. Free-form hosted questions require a signed-in Studio account and the configured hosted provider.

Local software help

In the documentation-help development build, ask How do I change the exposure of a clip? in either Command K or Studio Operator. A curated match opens the local help reader with the documented steps. Use Read source in this app to jump to the matching section, or Source online to open its canonical page. Internet and sign-in are not required for local help.

Select Software help only to keep any wording in the local instructions route. Automatic recognition also handles how-to questions and known feature questions. Help does not inspect or share a staged screenshot, prepare a viewport frame, or run an action. Images you added remain staged for a later visual question; they are not used as evidence for the help answer.

The first curated answers cover authored Color-node Exposure, viewer EV and the one-time HDR Mastering Use Current View as Starting Point copy. Does viewer EV change my export? is another direct local example. A mixed request such as Explain exposure, then set this node to +1 asks you to choose instructions or an action. To make an edit, turn off Software help only and submit the action explicitly, for example Change this node's exposure to +1 stop; normal validation and authorization still apply.

Unmatched wording returns a local clarification and offers the searchable library. Questions that require synthesis can send a bounded set of compatible documentation excerpts to the hosted model; the answer returns matching local and online citations. Cached documentation does not make the hosted model available offline. Browse Studio Help and the Help → AlexPearce3D Studio Help… menu are available for direct browsing.

External agents through MCP

  1. In Studio, open What can Studio do? and choose Connect an Agent.
  2. Review the project, Comp scope, tool set and expiry.
  3. Choose Copy Codex Config and add the block to the agent's MCP config.
  4. Ask the agent to call context.get before it inspects or changes the graph.
  5. After an edit, inspect the graph again and compare the returned revision and node IDs.

The copied configuration binds the agent to one explicit, expiring Studio session. Revoke it from Studio when finished. If the session expires, reconnect and copy a fresh block. Always use the ap3d executable inside the same Studio bundle that created the session.

For a visual MCP question, the agent prepares one bounded frame with comp.preview.prepare, checks it with comp.preview.inspect, then requests the image with comp.preview.read. Studio asks for local approval before disclosing the exact image.

Direct CLI

The bundled CLI is useful for deterministic automation and diagnostics:

"/path/to/AlexPearce3D Studio.app/Contents/MacOS/ap3d" agent sessions --json
"/path/to/AlexPearce3D Studio.app/Contents/MacOS/ap3d" agent capabilities \
  --session session-... --json
"/path/to/AlexPearce3D Studio.app/Contents/MacOS/ap3d" agent invoke \
  --session session-... --request-file request.json

Keep the request's session, context, document, graph and revision values from the same current capture. For an uncertain retry, reuse the same request ID and identical body. A changed body requires a new request ID and a fresh context.

Recovery

  • Stale context or revision: call context.get again, reinspect and rebuild the proposed edit against the returned IDs.
  • Revoked or expired connection: reconnect in Studio and replace the old MCP configuration.
  • Multiple Studio copies are running: use the exact session ID and bundled CLI from the connection sheet.
  • Invalid node or port: call nodes.describe, then use the exact node kind, parameter and port contract it returns.
  • Visual evidence unavailable: continue with graph/playhead metadata or add an explicit screenshot; do not infer image content.
  • Hosted prompt asks for sign-in: sign in to Studio, then submit again. Local typed graph commands and an already connected external agent remain separate paths.

Development status

  • Local typed Comp edits, direct CLI and local MCP graph inspection/editing are implemented on the current development branch.
  • Request-time current/named-frame evidence, explicit screenshots and matched before/after evidence are implemented with exact-set disclosure review.
  • Hosted documentation synthesis is available through the signed-in documentation route when compatible excerpts are found. Hosted visual interpretation still requires a signed-in account and explicit image disclosure.
  • Seedance and SAM replacement guidance is implemented in the current development branch. Release availability still depends on a qualified Studio build and the configured provider and local tracking runtimes.

This is development QA guidance. It does not qualify a release build.