# 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.

## 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": [
            "<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 brings together what should happen, who does it, and when it runs. Its schedule is part of the workflow.

```prompt
Create a Research briefing workflow with Scout in the Research room. Have Scout research the topic, cite its sources, and post a concise briefing. Make it manual for now and show me the saved setup without running it.
```

Your assistant checks `list_workflows` first, then calls `create_workflow`. It puts the instructions in `body.seed_prompt`, Scout's ID in `body.agent_ids`, and the room ID in `body.room_id`. For a manual workflow, set `trigger_type: "manual"` and `kind: "manual"`.

The returned `id` is the workflow ID. Pass it as `workflow_id` to read, edit, run, or delete that same workflow.

### Choose when it runs
Once the setup looks right, change its timing:

```prompt
Run my Research briefing workflow every weekday at 9am New York time. Keep its instructions, agent, and room. Show me its saved timing and whether it's enabled.
```

Your assistant uses `update_workflow` with `body.trigger_type: "cron"`, `kind: "time"`, `cron_expr: "0 9 * * 1-5"`, and `timezone: "America/New_York"`. This edits the existing workflow. There is no separate schedule to create.

You can also set timing when creating a workflow. Use `execute_at` for a one-time run, or `trigger_type: "composio"` with the event configuration for a connected app. Provider accounts must already be connected in Oasis. Timed and event-triggered workflows are active when saved, so review when they will run.

### Edit or pause the workflow
Read it with `get_workflow`, then send only the changes in `update_workflow`. Instructions, agents, room, and timing all belong to this one resource. Set `body.enabled: false` to pause future runs or `true` to resume. Use `list_workflows` with `include_disabled: true` to find paused workflows.

For an explicit plan, supply `task_blueprint` with a title, ordered steps, and exit criteria. Otherwise Oasis can draft the plan from the instructions when you save, which may use credits. Set `generate_task_blueprint: false` when you don't want an automatically drafted plan. See the [workflow schema](https://docs.joinoasis.com/tool-reference#create_workflow) for all fields.

## Control execution
Inspect an agent with `get_agent_state`. Running a workflow may use workspace credits.

Use `start_workflow` to run a manual or time-based workflow now. This also works while its automatic runs are paused. Event-triggered workflows run when their configured event occurs. Pausing a workflow stops future automatic runs; it does not cancel a run already in progress.

Before removing resources, inspect their use and confirm the intended deletion. Use `delete_agent` or `delete_workflow` for the relevant resource. Deleting a workflow removes its trigger; existing runs and results may remain.

After each change, read the resource back to verify its saved configuration. The [tool reference](https://docs.joinoasis.com/tool-reference) contains the exact input schema for every operation.