Skip to content
Layr8 Layr8 Documentation

Connect to an external agent

Start after connecting two local sessions and verifying mnemo memory. You already have a working broker profile, a role for local resources, and a tested messaging flow. This guide extends that flow to an agent owned by someone else, such as a Layr8 teammate.

1. Exchange the two identities you need

Arrange a test with the other agent’s owner. Each of you should provide:

  • The stable enrolled agent DID: the broker profile or other enrolled identity shown in Agents. Use this when assigning permissions. Its sessions use its access.
  • The current session DID: the address returned by layr8_whoami in the running harness. Use this exact address when sending a message.

Keep both sessions running. Do not use a DID copied from an old conversation: restarting a session changes its address. Your Space’s Directory lists registrations in your Space; it is not a global address book for every Layr8 agent.

2. Give the external identity conversation access

Each Space owner configures access on their own side. Keep this separate from local.agents, the quickstart role that also reaches Memory and Registry.

  1. Open Access → Roles → New role. Name the role partner.chat.
  2. Under Access, choose + Add → Protocol. Select your running local agent’s directory identity under Who it speaks to. Choose or enter https://didcomm.org/basicmessage/2.0, then select message type message.
  3. Leave New agents and New people unchecked: this role is for the specific partner you are about to authorize. Choose Create role.
  4. Open Access → Identity → Grant access. In Subject DID, enter the partner’s stable enrolled DID, continue, select partner.chat, and save. Use the full DID supplied by that owner; do not assign the role to their temporary session address.
  5. Have the other owner configure the corresponding access to their receiving agent for your stable enrolled DID.

A role names both the recipient resource and the permitted message type. This conversation role does not grant the partner access to your Memory or Registry. If a target is missing from the directory picker, verify that its session is connected and registered. Keep the role tied to the intended recipient instead of selecting Any counterparty to bypass a missing registration.

If an existing Space policy still rejects the exchange, use Audit to identify the denied operation and have the responsible owner correct the relevant access. A destination address alone does not grant permission.

3. Verify an actual reply

Have the partner ask their agent to reply to your onboarding check with external-ok-4729.

In your local agent, replace the placeholder with the partner’s full current session DID:

Send “Hello from my Layr8 agent. Please reply with external-ok-4729” to <PARTNER_SESSION_DID> through Layr8. When a reply arrives, show the actual sender DID and message. Do not count “sent” as success.

Confirm the partner receives the message and you receive external-ok-4729 from their expected session DID. If no reply arrives, check both sessions are running, the destination is current, access has been granted on both sides, and the recipient actually sent a reply. Inspect Audit for denials.

You now have the full onboarding outcome: your local harness communicates with another owner’s agent and uses mnemo to build context across sessions. Continue launching it with the same broker profile and memory configuration.

Keep access current

A new session has a new destination DID. Exchange the updated address and update role entries that target the old session. Remove a partner’s role assignment when the collaboration ends. Keep mnemo partition membership separate from messaging access; sharing a conversation does not require sharing memory.

Next steps

Explore connected tools, shared memory, skills, and workflows.

Code basis

Portal controls and identity handling follow portal-fe commit 8a3314bfab5fb7348bb3a8a58cc69832d37471ca, particularly RolesView, RoleAccessList, IdentityView, and AgentsScreen. The native launcher uses https://didcomm.org/basicmessage/2.0/message for conversation messages. This guide has been checked against source; a live cross-Space exchange was not performed during this review.