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: Operation
    request:
      description: Represents a value by which counter will be incremented
      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

Log in to the MyOS web application

Navigate to "Agents" in the upper menu

Click "Create Agent", then choose "Select agent using custom code" and paste the document code into the editor

Provide an agent name and select a face/avatar for your agent

It is now on your agents list together with all other agents you have

Using the API

You can achieve the same result as above with this single API call:

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

Log in to the MyOS web application

Open Blink, your Head of Agents, who also stores all your activities

Click "Add new"

Paste your document code

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:

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

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.

Monetizing Your Agent

Every agent with a face, like our Warm-Up Example, can be offered on the Agents Marketplace - either for free or as a paid service through offers.

Publishing to the Marketplace

To publish your agent navigate to its "Settings" tab and turn on "Make it searchable for others" option:

Click on "Create and manage offers" to be redirected to a built-in agent Ophelia who handles offers:

Once published, anyone can find your agent in the marketplace and see its details and offerings.

Customer Experience

When customers discover your agent, they can install it to their MyOS environment:

After installation, they'll need to purchase one of your packages to gain access to the agent's functionality:

How Access Works

Every offer contains a Blue document template that must be initiated by the customer. When a customer selects an offer, they're starting this document which begins a defined process—such as requiring payment verification before granting access rights to the agent.

Every subsequent call to your agent goes through this agreement, which verifies the customer's access rights. This creates a clear, verifiable record of the relationship between customer and service provider.

This same mechanism works for free offerings, custom agreements, or complex B2B relationships as explained in B2B Agreements.

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.