Your First Document in MyOS

This tutorial walks you through creating and interacting with a simple counter in MyOS. You'll learn about the two ways to run documents in MyOS, how to create them, interact with them, and include them in collaborative workspaces.

Understanding Documents in MyOS

Everything in MyOS is powered by Blue documents. These documents can be presented in two ways:

Agents with Faces

• Have a visual avatar representation
• Appear in the Agents section with a dedicated interface
• Ideal for tools you'll share with others
• Visually represented in chats and workspaces

Activities

• Don't have a visual representation
• Appear in a list format (similar to email)
• Better for personal use or one-off documents
• Represented by initials in a circle when added to chats

Both have identical functionality - the difference is purely in presentation.

The Counter Document

Let's start with a basic counter document in Blue:

name: Warm-Up Example
description: A simple demo document
counter:
  description: Some important counter
  value: 0
contracts:
  # Creates a dedicated timeline for the account that runs this document
  ownerChannel:
    type: MyOS Account Owner
  
  # Enables chat functionality
  chatOps:
    type: Chat Operations

  # Defines the increment operation interface
  increment:
    type: Request Response Operation
    request:
      description: Represents a value by which counter will be incremented
      type: Integer
    response:
      description: Counter value after incrementation
      type: Integer

  # Implements the increment operation
  incrementImpl:
    type: Sequential Workflow Operation
    operation: increment
    steps:
      - type: Update Document
        changeset:
          - op: replace
            path: /counter
            val: ${event.value + document('/counter/value')}
    response:
      type: Integer
      value: ${document('/counter/value')}

Method 1: Creating an Agent with a Face

Using the MyOS Web App

1. Log in to the MyOS web application
2. Navigate to "Agents" > "New Agent"
3. Paste the document code into the editor
4. Provide an agent name
5. Select a face/avatar for your agent
6. Click "Create"

Using the API

curl -X POST https://api.myos.blue/agents \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "name: Warm-Up Example\ndescription: A simple demo document\n...",
    "agentName": "Warm-Up Example",
    "agentFaceId": 45
  }'

Note: Both agentName and agentFaceId (a number between 0-1000) are required for agents with faces.

Method 2: Creating an Activity

Using Blink in MyOS

1. Log in to the MyOS web application
2. Open Blink, your Head of Agents, who also stores all your activities
3. Click "New"
4. Paste your document code
5. Click "Create"

Your document will appear in your list of activities, similar to an email inbox.

Using the API

curl -X POST https://api.myos.blue/agents \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "name: Warm-Up Example\ndescription: A simple demo document\n..."
  }'

Interacting with Your Counter

Whether you created an agent or activity, you'll have the same interaction capabilities:

The Interface

Both agents and activities share a consistent interface with two main tabs:

• Details tab: Shows the document's current state and includes several sub-sections:

  • Main: Overview with creation date and status
  • Description: The document's purpose
  • Current state: Live values of document fields
  • Participants: Channels document processor listens to
  • All actions: Available operations
  • Source: The original document Blue code as YAML

• Activity tab: Shows the interaction history and allows communication with the document

Blink Insights

A powerful feature of MyOS is how Blink automatically analyzes your document and provides human-readable summaries. In the blue section labeled "Blink Insights," you'll see:

• A clear explanation of what your document does
• Key features broken down into bullet points
• The current state explained in natural language

This makes even complex documents easy to understand for non-technical users.

Using the Activity Interface

In the Activity tab, you can interact with your document in several ways:

1. Operation requests: Type "increment the counter by 5" and Blink will translate this into a proper operation call, matching format defined in the document.

2. Regular messages: Since we enabled Chat Operations, you can also send normal messages.

Using the API

API calls work identically for both agents and activities:

# To increment the counter
curl -X POST https://api.myos.blue/agents/{id}/increment \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '5'

# To send a chat message
curl -X POST https://api.myos.blue/agents/{id}/chat \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '"Hello from the API!"'

From outside it's impossible to differentiate if the request was made through API or through Blink. In both cases a proper request will be sent to Bob's timeline and that will result in processor doing the changes.

Sharing Your Counter

Both agents and activities can be shared:

1. Navigate to the "Settings" tab
2. Under "Sharing", click "Add User"
3. Enter the email of the user you want to share with
4. Select which operations they can access

Agents with faces are more visually recognizable when shared, but both types have identical sharing capabilities.

Adding to Workspaces

You can include either agents or activities in collaborative workspaces:

1. From your counter, click "Add to Workspace"
2. This creates a new workspace where all participants can interact
3. Agents appear with their face/avatar
4. Activities appear as a circle with initials

Workspaces in MyOS are collaboration hubs where you can:

• Bring together multiple people and agents
• Create structured subtasks (which are themselves Blue documents)
• Maintain context for an ongoing project or relationship
• Track progress across multiple related activities

Setting Up Automated Tasks

Creating tasks in workspaces is simple:

1. Type: "When the counter reaches 15, notify me"
2. Blink will present a summary of the task
3. Confirm the creation

Blink generates a document for your task and embeds it in the workspace. Now, whenever your counter reaches 15, you'll receive a notification.

You can create multiple tasks within a workspace to:

• Connect different agents together
• Automate common processes
• Delegate specific responsibilities to different participants
• Create conditional logic between activities

Creating Workspaces via API

Under the hood, a MyOS Workspace is a Blue document with specific contracts available. You can create workspaces programmatically:

curl -X POST https://api.myos.blue/agents \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "name: Our Workspace\ntype: MyOS Workspace\ncontracts:\n  aliceTimeline:\n    type: MyOS Timeline\n    email: alice@xyz.com\n  someAgent:\n    type: MyOS Agent\n    agentId: 1234"
  }'

The document structure for a workspace typically looks like:

name: Our Workspace
type: MyOS Workspace
contracts:
  aliceTimeline:
    type: MyOS Timeline
    email: alice@xyz.com
  someAgent:
    type: MyOS Agent
    agentId: 1234

A MyOS Workspace is simply a base document with Chat Operations, Access Management Operations, and Subnodes Operations already activated (see Operations for more details). The main elements you need to specify are the channels that represent participants - both human users and agents.

Once created, you can interact with the workspace through standard API calls:

# To send a message to the workspace
curl -X POST https://api.myos.blue/agents/{workspaceId}/chat \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '"Let\'s discuss the project plan"'

Every time you create a workflow or subtask within a workspace, you're effectively creating a new agent that processes its own document, all within the context of the parent workspace.

Choosing Between Agents and Activities

Use an Agent with a Face when:

• You want to create a sharable tool or service
• You plan to offer it in the Agents Marketplace
• Document uses REST API calls to your API
• It needs a distinctive visual identity for recognition
• It will be used repeatedly across multiple contexts

Use an Activity when:

• You're creating agreements or collaboration documents
• It represents a specific transaction or interaction
• It's part of a larger workflow or process
• You're making something primarily for personal use

Remember that while both have the same technical capabilities, they serve different purposes in the MyOS ecosystem. Agents are designed to be shared services, while activities are typically interaction-specific documents.