# send_agent_message

Send a message to a Layer agent and start its turn. Returns at once with \`session\_id\` and  
\`turn\_id\`; wait for the answer with get\_agent\_response. Each turn's own model work is billed in  
Creative Units.

The answer is often a question or a plan to confirm: reply by calling this tool again with the  
same \`session\_id\`. Only one turn runs at a time in a session; sending while one runs fails with  
TURN\_IN\_PROGRESS.

IMPORTANT: Call tool \`get\_instructions\` first for general platform guidance.

## Parameters

| Parameter        | Type                | Default | Description                                                                                                                                                                                                                                                        |
| ---------------- | ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| workspace\_id    | string (uuid)       | —       | The user's workspace ID. Required to start a session; omit it when continuing one.                                                                                                                                                                                 |
| messagerequired  | string1–20000 chars | —       | What to tell the agent.                                                                                                                                                                                                                                            |
| agent\_id        | string              | —       | The agent to talk to, from list\_agents. Required to start a session. On a follow-up, omit it and the agent that last replied answers again; pass it when no agent has replied yet (for example after a canceled or failed first turn).                            |
| session\_id      | string (uuid)       | —       | The session to continue, from list\_chat\_sessions or an earlier result. Omit to start a new session.                                                                                                                                                              |
| project\_id      | string (uuid)       | —       | Project to file a new session under. Ignored when continuing a session.                                                                                                                                                                                            |
| file\_ids        | string (uuid)\[\]   | \[\]    | Files to attach, e.g. reference art, uploaded with request\_file\_upload\_url.                                                                                                                                                                                     |
| idempotency\_key | string0–128 chars   | —       | A unique string for this message; always pass one. A retry with the same key returns the original turn instead of starting a second one.                                                                                                                           |
| effort           | enum                | —       | How hard the agent's builder works; list\_agents \`round\_estimates\` gives each level's price and time per build round. Omit it to keep the session's effort (medium for a new session): a plan is priced at the effort it was asked at.One of: low, medium, high |