[Python SDK] Agent.stop() is not implemented

[santoshkumarradha]

Summary

agentfield.Agent has no stop() method. The TypeScript SDK's Agent class exposes a symmetric serve()/shutdown() (or start()/stop()) lifecycle, and the documentation in several places implies the Python SDK has the same. Today it does not, which means external callers cannot programmatically stop a long-running agent without going through signal handling — a leaky abstraction.

Where

• File: sdk/python/agentfield/agent.py
• Class: Agent
• Discovered by: sdk/python/tests/test_agent_graceful_shutdown.py::test_agent_stop_is_idempotent (skipped with pytest.skip("source bug: Agent.stop() is not implemented"))

Reproduction

agent = Agent(
    node_id="shutdown-agent",
    agentfield_server="http://agentfield",
    auto_register=False,
    enable_did=False,
)
hasattr(agent, "stop")  # False

Expected behavior

Agent.stop() should:

1. Mark the agent as shutting down (set _shutdown_requested = True, transition _current_status to OFFLINE)
2. Stop the heartbeat loop
3. Notify the control plane via client.notify_graceful_shutdown (best effort — failure should not block stop)
4. Tear down async resources (the same path as _cleanup_async_resources)
5. Be idempotent — calling stop() twice should be a no-op the second time, not raise

This pairs cleanly with whatever start/serve method the agent already exposes.

Acceptance criteria

• Agent.stop() exists and is async
• Calling it transitions status, stops heartbeat, notifies control plane (best effort), and tears down async resources
• Calling it twice does not raise
• The skipped test in test_agent_graceful_shutdown.py::test_agent_stop_is_idempotent is unskipped and passes
• Stop semantics documented in the Agent docstring

Related

• See also [Python SDK] graceful shutdown does not track or cancel in-flight tasks #356 ("graceful shutdown does not track in-flight tasks") and [Python SDK] graceful shutdown does not enforce timeout-based task cancellation #357 ("graceful shutdown does not enforce timeout cancellation") — those issues affect the underlying _graceful_shutdown machinery that stop() should drive.

Discovered via

PR #352 (test coverage improvements). One of 5 source bugs surfaced while writing failure-mode tests for the Python SDK.

[shuaixr]

@santoshkumarradha Hi👋, I would like to work on this.

[santoshkumarradha]

@shuaixr all yours !

[github-actions]

Thanks for picking this up, @shuaixr! 🎉

Here's what to expect:

• We'll check in after 7 days if we haven't heard an update
• After 14 days, we'll send a second reminder
• After 21 days without activity, we'll unassign to let others contribute

Tips for success:

• Drop a comment when you start working on it
• Share any blockers - we're here to help!
• Link your PR with Fixes #355 in the description

Happy coding! 🚀