MyOS Agents as Processors

MyOS agents are fundamentally Blue document processors with enhanced capabilities. When you create an agent in MyOS, you're essentially deploying a specialized processor dedicated to a specific document. As seen in the Quick Start example, these processors provide additional functionality beyond what's possible with standard Blue processing.

MyOS Timelines

MyOS Timelines are managed by the MyOS platform. Documents can reference these timelines through specific contracts that indicate which timelines should be used during processing.

Including Timelines in Documents

There are several ways to include a MyOS timeline in your document:

1. Reference by Timeline ID

To include all events from a specific timeline from the beginning:

aliceTimeline:
  type: MyOS Timeline
  timelineId: 1234

This adds a channel that processes all events from this timeline, starting from the very first event.

2. Reference with Checkpoint

To start processing from a specific point in the timeline:

aliceTimeline:
  type: MyOS Timeline
  timelineId: 1234

checkpoint:
  type: Channel Event Checkpoint
  lastEvents:
    aliceTimeline:
      blueId: vHkzPa8Ypd5KJsLNcA3FV6xDqbn7UEBwTmRMfQ92rGt4

This approach processes only events that occur after the specified checkpoint.

3. Reference by User Identity

You can also reference a timeline by a user's email or account ID:

aliceTimeline:
  type: MyOS Timeline
  email: alice@xyz.com

Or:

aliceTimeline:
  type: MyOS Timeline
  accountId: 12345

How MyOS Handles Timeline References

When MyOS encounters a timeline reference by email or account ID, it automatically:

1. Creates a timeline for the specified user if needed
2. Updates the document with the actual timeline ID
3. Grants the processing agent read access to this timeline
4. Grants all necessary permissions for the newly created timelines to the agent processing this document
5. Notifies the account owner about their inclusion in the document

For example, if you start a document with:

name: Some Doc
contracts:
  aliceTimeline:
    type: MyOS Timeline
    email: alice@xyz.com
  
  bobTimeline:
    type: MyOS Timeline
    email: bob@xyz.com

After processing, MyOS will update the document to include:

myOSProcessor:
  type: MyOS Processor
  timelines:
    aliceTimeline:
      type: MyOS Timeline
      timelineId: 1234
    bobTimeline:
      type: MyOS Timeline
      timelineId: 2345

This automatic timeline creation and access management is one of the key benefits of using MyOS as your processor.

MyOS Agents

MyOS agents can reference other agents, allowing agents processing documents to interact with each other.

Referencing Other Agents

To reference another MyOS agent:

someAgent:
  type: MyOS Agent
  agentId: 1234

Two Primary Uses for Agent References

1. Listening to Events

You can listen to events triggered by another agent:

someAgentChannel:
  type: MyOS Agent Channel
  agent: someAgent
  event:
    type: Terminate Contract Event

This creates a channel that contains events from the referenced agent, starting from when the document processor begins listening. Unlike timeline references, agent channels do not include historical events - only new events from the moment of connection forward.

2. Calling Operations

You can call operations provided by another agent within a Sequential Workflow:

someOperationImpl:
  type: Sequential Workflow
  operation: reserveLesson
  steps:
    - name: CallSecretary
      type: Call Agent
      agent: someAgent
      operation: reserveLesson
      params:
        beginning: ${ request }
        duration: ${ document('/lessonDuration') }

The Call Agent step is a MyOS-specific enhancement that allows direct invocation of operations from other agents. The result from the operation call is available in the response variable, and any errors are captured in the errors object.

Access Granting in MyOS

For the agent interactions described above to work, proper permissions must be granted to the agent processing the document. This is where MyOS's access control system becomes essential.

Extending Blue's Security Model

While standard Blue documents provide security through document-defined rules and contracts, MyOS adds an additional layer of agent-level permission management. This builds on Blue's fundamental security features:

• In standard Blue, a document's security is defined through its contracts and rules
• MyOS extends this by adding explicit agent-to-agent access controls
• This allows for sophisticated permission management while maintaining the document-centric security model

Account-to-Agent Access

As demonstrated in the Quick Start example, an account owner can share their agent with another account. This MyOS feature allows controlled access to agent operations through the user interface or API.

Agent-to-Agent Access

More powerful is the ability for agents to grant access to other agents. This is implemented through specialized Agent Access Grant documents:

name: Example Access Grant
type: Agent-to-Agent Access Grant

targetAgent:
  agentId: 123
  owner: 234

callingAgent:
  agentId: 567
  owner: 789

targetAgentExposedOperations:
  - name: capture
    request:
      currency: USD

callingAgentDocumentRequirements:
  - type: Document Contains
    content:
      name: Abc
  - type: JavaScript Condition
    expression: ${document("/availableTokens") > 0}

This grant document specifies:

1. Which agent is being granted access (callingAgent)
2. Which agent is providing access (targetAgent)
3. Which operations the calling agent can invoke
4. What conditions the calling agent's document must satisfy

The ability to set granular, conditional access requirements creates a powerful trust mechanism for inter-agent collaboration. This allows agents to safely expose specific functionality to other agents while maintaining control over how that functionality is used.

MyOS's access granting system transforms individual agents into a cooperative ecosystem, where complex relationships between documents and their processors can be managed with security and precision - all while building on Blue's core security principles.