> For the complete documentation index, see [llms.txt](https://agpt.co/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://agpt.co/docs/integrations/block-integrations/create_session.md). # Conductor Create Session Starts a new agent session (chat) in an existing Conductor workspace, optionally with a first prompt, and optionally waits for the reply. Requires your own Conductor API key, created at [app.conductor.build/users/api-keys](https://app.conductor.build/users/api-keys) and added through AutoGPT’s credentials UI. Select that credential for each Conductor block; no server-wide default key is used. ## Conductor Create Session ### What it is Start a new agent session (chat) in an existing Conductor workspace, optionally with a first prompt, and optionally wait for the agent's reply. ### How it works The block posts to `POST /v0/sessions` with `workspaceId`, `agent` and any non-blank `model`, `effort`, `name` or `message`. When `message` is given the returned `initial_message_id` identifies the prompt and `next_after` is the prompt's transcript row ID to pass as `after` to Get Session (the receipt itself while the prompt is still queued, which Get Session also accepts); with `wait_for_reply` the block waits the same way as Send Message: it reads the transcript and then the session status on every poll (a wall-clock bound of `timeout_seconds`, reported through `timed_out`), correlates the rows with the prompt's turn, treats the session as done only once it is idle after the turn progressed past its startup events, and returns the rows in `messages` with their visible agent text joined into `reply` (`truncated` is set when the turn exceeded the 1000 rows kept or its start was older than the rows read). ### Inputs | Input | Description | Type | Required | | ----------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -------- | | workspace\_id | Workspace to add the session to | str | Yes | | message | Initial prompt for the agent; leave empty for an idle session | str | No | | agent | Agent to run | "claude" \| "codex" \| "cursor" \| "acp" | No | | model | Model id such as fable-5-1, opus-5-5-1m, sonnet-5-1m, gpt-6-astra or auto. Leave empty for Conductor's default. | str | No | | effort | Reasoning effort; leave empty for the default | "" \| "none" \| "low" \| "medium" \| "high" \| "xhigh" \| "max" \| "ultra" | No | | fast\_mode | Enable fast mode | bool | No | | name | Session name | str | No | | wait\_for\_reply | After sending the initial prompt, wait until the agent is idle and return its reply | bool | No | | timeout\_seconds | How long to wait for the reply | int | No | | poll\_interval\_seconds | Seconds between status checks while waiting | int | No | ### Outputs | Output | Description | Type | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | | error | Error message if the operation failed | str | | session\_id | ID of the new session | str | | deep\_link | Link that opens the session | str | | initial\_message\_id | ID of the initial prompt message, empty when none was sent | str | | next\_after | Transcript row ID of the prompt's row; pass it as `after` to Get Session to read the agent's turn. Falls back to initial\_message\_id while the prompt has no row yet, which Get Session also accepts | str | | session\_status | idle, working or error once waiting finished | str | | reply | Text the agent produced in response | str | | messages | Raw transcript messages after the prompt | List\[Dict\[str, Any]] | | timed\_out | True when the wait ended before the agent went idle | bool | | truncated | True when the turn produced more messages than are kept; messages holds the newest ones and reply may be incomplete | bool | | error\_message | Session error, if any | str | ### Possible use case **Second opinion**: Open a Codex session in a workspace where Claude already worked and ask it to review the diff. **Split work**: Start one session per sub-task in the same workspace so they share the checkout. *** --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://agpt.co/docs/integrations/block-integrations/create_session.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.