Add cross-agent-handoff example (shared session across agents) by HarshaNalluru · Pull Request #387 · usemoss/moss

HarshaNalluru · 2026-07-13T22:24:58Z

What

A small, runnable example under moss-live-labs/examples/cross-agent-handoff that moves a conversation between agents without the customer repeating themselves, using one shared Moss session.

The idea

Each agent keeps its own private context, so a handoff (chat to voice, bot to human, phone to laptop) usually resets to zero. Instead, all agents share one named session. Agent A writes the conversation and pushes it; Agent B opens the same session by name, resumes it (no re-embedding), and queries context it never directly received.

# --- agent A (chat) ---
session = await moss.session(index_name="call-8821")
await session.add_docs([...])            # the conversation turns
await session.push_index()               # hand off to the cloud

# --- agent B (voice, different client) ---
session = await moss.session(index_name="call-8821")   # same name -> resumes
ctx = await session.query("was a refund promised?", QueryOptions(top_k=1))

cross_agent_handoff.py — simulates two independent agents in one process: A pushes a session, B (a fresh client) resumes it and answers about the charge, the refund, and the order number, none of which it was told directly
README.md, .env.example, .python-version, pyproject.toml, uv.lock

Run

uv sync && cp .env.example .env   # Moss keys
uv run python cross_agent_handoff.py

Notes

Mirrors the structure and API of the existing semantic-cache example (moss.session(index_name=...), add_docs, push_index, query).
Draft: syntax-checked and uv lock resolves, but I have not run it against a live Moss project in this environment (no credentials here). Worth a quick uv run before merge to confirm B sees A's pushed context.

github-actions · 2026-07-13T22:27:02Z

+
+    # unique per run so the demo starts clean; in production use a stable id such
+    # as the call / conversation id so the same session is resumable later.
+    session_name = f"call-handoff-demo-{uuid.uuid4().hex[:8]}"


CONSIDER session_name = f"call-handoff-demo-{uuid.uuid4().hex[:8]}"

Because this session is immediately push_index()ed, every run creates a new cloud index with a random name and no cleanup path. That can leak indexes/docs into a user's project just from trying the demo. Either use a stable demo name that is reused, or clean up in main() after the handoff completes, e.g. try: ... finally: await _client().delete_index(session_name).

github-actions · 2026-07-13T22:27:03Z

Codex review

The new live-labs handoff example is straightforward and mostly follows the existing session pattern. The main concern is that the runnable demo leaves persistent cloud state behind on every execution.

Copilot

Pull request overview

Adds a new experimental runnable Python example under moss-live-labs/ demonstrating cross-agent handoff by having multiple agents share a single named Moss session (agent A writes + pushes; agent B resumes and queries).

Changes:

Introduces a new cross-agent-handoff example script that simulates two independent agents using the same session name.
Adds minimal project scaffolding for running the example via uv (pyproject, lockfile, env template, python version pin).
Documents the concept and run instructions in a new README.

Reviewed changes

Copilot reviewed 5 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
moss-live-labs/examples/cross-agent-handoff/cross_agent_handoff.py	New runnable example simulating agent A session push and agent B resume/query flow.
moss-live-labs/examples/cross-agent-handoff/README.md	Explains the handoff concept and how to run the demo.
moss-live-labs/examples/cross-agent-handoff/pyproject.toml	Defines a small `uv` project with `moss` + `python-dotenv` dependencies.
moss-live-labs/examples/cross-agent-handoff/uv.lock	Pins resolved dependencies for reproducible installs.
moss-live-labs/examples/cross-agent-handoff/.env.example	Template for required Moss credentials.
moss-live-labs/examples/cross-agent-handoff/.python-version	Pins the example’s Python version to 3.12.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+## Resources
+
+- [Docs](https://docs.moss.dev/docs/build/cross-agent-handoff)


+def _client() -> MossClient:
+    return MossClient(
+        project_id=os.environ["MOSS_PROJECT_ID"],
+        project_key=os.environ["MOSS_PROJECT_KEY"],
+    )


…g creds, root docs link

HarshaNalluru · 2026-07-14T21:06:11Z

Addressed the review:

Demo cleanup: main() now wraps the handoff in try/finally and calls delete_index(session_name), so a demo run no longer leaves a random cloud index behind.
Fail-fast creds: _client() reads MOSS_PROJECT_ID/MOSS_PROJECT_KEY via a _require() helper (os.getenv + clear exit message) instead of os.environ[...], so missing creds fail cleanly even if the helpers are called directly.
Docs link: README now points to the root https://docs.moss.dev (with UTM), matching the other examples.

Copilot

Pull request overview

Copilot reviewed 5 out of 6 changed files in this pull request and generated 2 comments.

+    # hand off: persist the session so any other agent can resume it
+    await session.push_index()
+    print("[agent A - chat]   wrote 3 turns and pushed the session to the cloud\n")


+The first agent opens a session by name, writes the conversation, and pushes it
+to the cloud. The second agent, a different process or device, opens the *same*
+session name. Because that index already exists, Moss resumes it (no
+re-embedding), and the agent can query context it never directly received:


HarshaNalluru · 2026-07-15T02:19:31Z

Addressed the latest review:

Deterministic handoff: agent_a_handles_chat now captures the push_index() result and await moss.wait_for_job(result.job_id) before agent B resumes, so the cloud index is fully ready to auto-load (no race).
README: updated the snippet to wait_for_job(result.job_id) after push_index(), plus a note that push_index() queues server-side processing and you should wait (or poll get_job_status) before another agent resumes.

Copilot

Pull request overview

Copilot reviewed 5 out of 6 changed files in this pull request and generated 4 comments.

+    # hand off: push to the cloud. push_index() queues a server-side indexing job,
+    # so wait for it to finish before another agent tries to resume the session.
+    result = await session.push_index()
+    if result.job_id:
+        await moss.wait_for_job(result.job_id)
+    print("[agent A - chat]   wrote 3 turns and pushed the session to the cloud\n")


+    finally:
+        # demo cleanup: this run pushed a cloud index, so remove it. In production
+        # you would keep the session (a stable, resumable id) instead of deleting it.
+        await _client().delete_index(session_name)
+        print(f"\ncleaned up demo session: {session_name}")


+result = await session.push_index()      # queues a cloud indexing job
+await moss.wait_for_job(result.job_id)    # wait until it's ready to resume
+


+`push_index()` doesn't finish instantly: it queues server-side processing and
+returns a `job_id`. Wait for that job (`wait_for_job`, or poll `get_job_status`)
+before another agent resumes the session, otherwise the index may not be ready
+to auto-load yet.


Add cross-agent-handoff example (shared session across agents)

520de6c

Copilot AI review requested due to automatic review settings July 13, 2026 22:24

Copilot started reviewing on behalf of HarshaNalluru July 13, 2026 22:25 View session

github-actions Bot reviewed Jul 13, 2026

View reviewed changes

Copilot AI reviewed Jul 13, 2026

View reviewed changes

HarshaNalluru marked this pull request as ready for review July 14, 2026 19:40

HarshaNalluru requested a review from r4ghu as a code owner July 14, 2026 19:40

cross-agent-handoff example: clean up demo index, fail-fast on missin…

da1aba5

…g creds, root docs link

Copilot AI review requested due to automatic review settings July 14, 2026 21:05

Copilot started reviewing on behalf of HarshaNalluru July 14, 2026 21:06 View session

Copilot AI reviewed Jul 14, 2026

View reviewed changes

cross-agent-handoff: wait for push_index job before agent B resumes

8016817

Copilot AI review requested due to automatic review settings July 15, 2026 02:19

Copilot started reviewing on behalf of HarshaNalluru July 15, 2026 02:19 View session

Copilot AI reviewed Jul 15, 2026

View reviewed changes

Navigation Menu

Uh oh!

Add cross-agent-handoff example (shared session across agents) - #387

Add cross-agent-handoff example (shared session across agents)#387
HarshaNalluru wants to merge 3 commits into
mainfrom
add-cross-agent-handoff-example

HarshaNalluru commented Jul 13, 2026

Uh oh!

github-actions Bot Jul 13, 2026

Uh oh!

github-actions Bot commented Jul 13, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

HarshaNalluru commented Jul 14, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

HarshaNalluru commented Jul 15, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		## Resources

		- [Docs](https://docs.moss.dev/docs/build/cross-agent-handoff)

		result = await session.push_index() # queues a cloud indexing job
		await moss.wait_for_job(result.job_id) # wait until it's ready to resume

Uh oh!

Conversation

HarshaNalluru commented Jul 13, 2026

What

The idea

Contents

Run

Notes

Uh oh!

github-actions Bot Jul 13, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jul 13, 2026

Codex review

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

HarshaNalluru commented Jul 14, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

HarshaNalluru commented Jul 15, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants