# Let’s build your Oasis > Create, configure, and control agents, rooms, and workflows. Let's build a research setup in your Oasis: an agent named Scout, a private room, a workflow with its own timing. Your coding assistant can create and manage each part through MCP tools. [Connect it to your workspace](https://docs.joinoasis.com/mcp) first. ## Find your agents Start with what's already in your workspace. Call `get_workspace` to verify the connection, then list the existing agents. Your assistant calls `list_agents`. The connection already identifies your workspace: ```json { "name": "list_agents", "arguments": {} } ``` To see one agent's instructions and settings, use `get_agent` with its returned `agent_id`. If several agents share a name, choose the one you mean. Keep these IDs for later configuration calls. If the list is empty, create an agent below. ## Create an agent Create Scout with a name, role, and standing instructions. Your coding assistant sends those fields to `create_agent`: ```json { "name": "create_agent", "arguments": { "body": { "name": "Scout", "agent_role": "Research analyst", "system_prompt": "Research industry news and write short briefings. Link to original sources and explain why each item matters. Label uncertainty. Ask before contacting people or changing external systems." } } } ``` Oasis automatically uses the current agent runtime. You don’t need to choose an agent type or model. Keep the returned agent ID. This creates the agent configuration. Room membership and workflow execution are separate operations. ## Start a room Create a place for the research team. Check `list_rooms` first so you can reuse an existing room if appropriate. Call `create_room` with a name, `visibility: "private"`, and Scout's ID in `body.agent_participants`. Use `body.human_participants` for existing workspace members. Keep the returned room ID as the destination for your workflow. Use `get_room` to inspect membership and `add_room_participant` to add an agent or human later. Rename or change visibility with `update_room`. Use `archive_room` and `restore_room` to manage the room's lifecycle. ## Edit the prompt Set the instructions Scout should use for its work: > Update Scout's instructions to start each briefing with a short summary, then findings and open questions. Keep its source requirements and other instructions. Your assistant reads Scout with `get_agent`, combines the change with its existing instructions, and calls `update_agent` with `body.system_prompt`. That field replaces the entire prompt, so include the instructions you want to keep. Then read Scout again to check the saved result. The prompt is part of the agent's saved configuration. Send only the fields you intend to change so its tools and other settings remain intact. ## Configure tools Use `list_agent_tools` to see Scout's tools and `list_tool_types` to discover available types. Add, edit, or remove a supported configuration with `create_agent_tool`, `update_agent_tool`, or `delete_agent_tool`. Provider accounts must be connected in Oasis first. Use `get_agent_state` to check runtime status without interrupting work. ## Control what each tool can do Each tool on a connected app runs in one of three modes for an agent: - **Auto** runs without asking. - **Ask first** posts an approval card, even for a tool that only reads. - **Off** hides the tool from the agent and refuses it if called. Tools you haven't changed follow their default: reads run automatically, and writes ask first unless that account has auto-approve on. ```prompt Turn off sending email for Scout, but let it keep reading my inbox. Show me which tools you changed. ``` Your assistant calls `list_agent_connections` to find Scout's linked accounts, then lists one account's tools with their exact slugs: ```json { "name": "list_connection_tools", "arguments": { "connection_id": "", "agent_id": "" } } ``` Then it sets the mode for each tool it means to change: ```json { "name": "set_agent_tool_mode", "arguments": { "agent_id": "", "body": { "toolkit": "gmail", "tool_slug": "GMAIL_SEND_EMAIL", "mode": "off" } } } ``` Send `mode: null` to put a tool back to its default, and call `list_agent_tool_modes` to read back what you changed. Modes are set per app: if Scout can also send email through another app, such as Google Workspace, turn off that app's send tool too. A mode never gives an agent more access than its account and permissions allow; `auto` only skips the approval card. ## Give your agents skills Skills are reusable instructions. Save one in your workspace library, then choose the agents that should use it: ```prompt Create a workspace skill called Greeting with the instruction “Always open your first reply in a conversation with a short greeting: say hi.” Check for an existing greeting skill first and ask before replacing it. Assign it to Mike without removing his other skills, then read back his skills to verify it was saved. ``` Your assistant calls `list_workspace_skills`, then saves the instructions: ```json { "name": "save_workspace_skill", "arguments": { "body": { "name": "Greeting", "slug": "greeting", "skill_md": "Always open your first reply in a conversation with a short greeting: say hi." } } } ``` Use the returned slug and Mike's ID from `list_agents` to give him the skill: ```json { "name": "assign_workspace_skills", "arguments": { "body": { "assignments": [ { "skill_slug": "greeting", "agent_ids": [ "" ] } ] } } } ``` Include more agent IDs to give the same skill to several agents. Existing skills stay assigned, and repeating the same assignment won't add a duplicate. Check each result's `status`: `attached` and `already_attached` succeeded; `failed` includes an error to resolve. Then call `list_agent_skills` for each agent to verify the result. To edit instructions, call `save_workspace_skill` again with the same slug. This replaces the skill's files, and attached agents pick up the change on their next turn. Use the Oasis app for ZIP bundles with scripts or supporting files. To remove a skill from one agent, read `list_agent_skills` and pass the remaining entries to `replace_agent_skills`. It replaces the **entire list**; an explicit empty `skills` array detaches everything. To remove the skill from the workspace and all affected agents, use `delete_workspace_skill` after confirming the deletion. Skills use these dedicated tools. Don't put inline skill content in `update_agent`; it doesn't create or assign skills. ## Invite a teammate Configure who has access to your workspace and rooms. Check `list_members` and `list_invites` first, then confirm the person's email and intended role before sending an invitation: > Invite teammate@example.com to my workspace as a member. Replace that example with the real recipient. The assistant calls `invite_human` with `body.email` and `body.role`. You need an owner or admin role and `oasis:invite` permission. After they accept, find their ID with `list_members`. Use `add_room_participant` with `body.human_id` to add them to Research. For another agent, use `body.agent_id` instead. Supply exactly one of those IDs per call. Invitations don't automatically add people to private rooms. ## Build a workflow A workflow needs a plan, assigned steps, and a trigger. Start by checking the authenticated workspace server's `tools/list`. The tools below are being rolled out; this guide does not mean every deployment already exposes them. Use only tools present in your live catalog. The documentation MCP is read-only and cannot create workflows. Copy this prompt into your connected assistant: ```prompt Build this workflow in my Oasis account: [describe the objective, steps, intended account, event or schedule, filters, and any explicit delivery action]. First check your live Oasis tools and existing workflows, including paused ones, to avoid duplicates. Discover the actual agents, connected account, trigger types and required configuration rather than guessing. Prefer build_workflow if available. Give each step an explicit assignee and clear completion criteria. Save paused, then read back the trigger, account, filters, ordered steps, dependencies and timing, and show me the workflow link. Do not run it or enable automatic runs yet. If a required authoring tool is missing, explain the specific limitation; do not claim the workflow is complete. ``` ### Discover the account and trigger Use `get_workspace`, `list_workflows` with `include_disabled: true`, and `list_agents` to identify the workspace, existing workflows, and real agent IDs. Use `list_members` for human assignees. When available, `list_connected_accounts` identifies your connected app accounts. Match the intended account by label and identity. Pass its `connected_account_id`, not its connection-row `id`. Do not silently choose the first account when several exist. Connecting a new provider account still happens in Oasis. For an app event, use `list_workflow_trigger_types` filtered by toolkit, then `get_workflow_trigger_type` for the selected slug. Read `config_schema` for required provider settings and `payload_schema` for filter fields. Never invent a trigger slug or payload path. Provider polling/search settings belong in `trigger.event.trigger_config`. Exact conditions for this workflow belong in `trigger.filters`: deterministic rules such as a subject containing a test marker. All rules must match. AI judgment belongs in the workflow instructions; it does not replace an exact sender or subject filter. To reuse a configuration from the editor, use `list_workflow_trigger_configs`, then `get_workflow_trigger` to check an event source's account, provider filters, subscription and enabled state. A saved configuration ID, provider trigger type and workflow ID are different identifiers. Shared sources can serve several workflows; do not edit a shared source merely to change one workflow's filters. ### Author the steps and timing If `build_workflow` appears in your live catalog, use it to build the plan and trigger together. Its schema defines the exact fields. Supply `name`, `objective`, ordered `steps`, a `trigger`, and `enabled: false` for review. Each step has a title, instruction, kind, position, assignees and optional dependencies. Positions start at zero. Use actual agent or human UUIDs in `assignees`; names alone do not assign work. For dependencies, give steps stable UUID `id` values and refer to those IDs in `depends_on_step_ids`. Human-assigned steps wait for human action, and at least one step must be assigned to an agent; a plan with only human assignees is rejected. Preserve existing IDs when editing a plan. Choose a manual trigger, a time trigger, a new app-event trigger, or a saved configuration according to the live schema. Timed workflows need an IANA timezone, such as `America/New_York`; weekday 9am is `0 9 * * 1-5`. A one-time timestamp must include an offset. A new event needs the selected toolkit, trigger slug, account, provider settings and workflow filters. ### Read back, edit and verify Read `get_workflow` and, when available, `get_workflow_plan`. Verify the selected account, event source, filters, enabled state, timezone and actual assigned steps. Keep the returned `workflow_id`, `task_definition_id` and `ui_url`. On older deployments the MCP workflow ID is the schedule ID while the frontend link uses a different task ID; never assume they are equal. Use `update_workflow_plan` for structured steps when available. Its steps input replaces the full plan, so preserve unchanged step IDs, assignments and dependencies. Use `set_workflow_filters` for workflow-specific filters on a shared event source; changing only legacy schedule fields may not change the shared trigger's effective filter. Use `update_workflow` for supported timing changes and `enabled: false` to pause future automatic runs. Pausing does not cancel a run already in progress. A saved trigger configuration and raw timing fields are not interchangeable; read the effective configuration after any edit. After authorization, `start_workflow` runs a manual or time-based workflow even while paused. Event workflows need their configured event. When available, `get_workflow_runs` shows the tasks created by the workflow. A successful save or scheduled wakeup is not proof that a message arrived: verify the run and any explicitly requested delivery action. If a build fails partway through, retain its recovery IDs and inspect the saved draft before retrying. A timeout may have occurred after a write completed. Do not create another workflow blindly. ### Older servers: legacy workflow creation If `build_workflow` is absent, `create_workflow` remains the legacy path. Put instructions in `seed_prompt`, participant IDs in `agent_ids`, and explicit agent assignments in the steps. Workflows execute through Task Manager private agent wakes; do not create or choose a destination chat. If the user requests a DM, model that delivery as an assigned step action. Set `trigger_type: "manual"` and `kind: "manual"` to save without automatic execution. For an explicit legacy plan, provide `task_blueprint` with `title`, nonempty string `steps`, and `exit_criteria`. Bind a step to an agent with `@[Name](agent:UUID)` using its real ID. Set `generate_task_blueprint: false` to avoid generating a replacement plan. This legacy string blueprint does not expose the full structured plan editor. Automatic triggers are active when created through the legacy tool. To stage safely, create manual, pause with `update_workflow`, then configure timing. Cron uses `trigger_type: "cron"`, `kind: "time"`, `cron_expr` and `timezone`; one-time runs use `execute_at`. Direct provider events use `trigger_type: "composio"` and the discovered provider configuration. Where discovery or shared-trigger tools are absent, use the Oasis editor for those steps rather than guessing. ## Control execution Inspect agents with `get_agent_state`. Running work may use workspace credits. Before removing a resource, inspect its use and confirm the intended deletion. Existing runs and results may remain after deleting a workflow. Customer rules such as working-hour SLA accumulation, reply matching, acknowledgment escalation, frequency caps and standards checks need their own implementation and test cases. A fire cap is a protective pause, not a rolling per-account delivery policy. Creating a workflow does not prove those rules work. The [tool reference](https://docs.joinoasis.com/tool-reference) is a generated snapshot. The authenticated server's `tools/list` is authoritative for your deployed capabilities and exact schemas.