Let’s build your Oasis

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 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:

{
  "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:

{
  "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.

Your assistant calls list_agent_connections to find Scout's linked accounts, then lists one account's tools with their exact slugs:

{
  "name": "list_connection_tools",
  "arguments": {
    "connection_id": "<gmail-connection-id>",
    "agent_id": "<scout-agent-id>"
  }
}

Then it sets the mode for each tool it means to change:

{
  "name": "set_agent_tool_mode",
  "arguments": {
    "agent_id": "<scout-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:

Your assistant calls list_workspace_skills, then saves the instructions:

{
  "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:

{
  "name": "assign_workspace_skills",
  "arguments": {
    "body": {
      "assignments": [
        {
          "skill_slug": "greeting",
          "agent_ids": [
            "<mike-agent-id>"
          ]
        }
      ]
    }
  }
}

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:

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 is a generated snapshot. The authenticated server's tools/list is authoritative for your deployed capabilities and exact schemas.