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 |